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PREFACE 



This document contains a description of Subroutines and I/O Modules provided 
as part of the standard Multics system. The subroutines can be called from PL/ 1 
programs to perform system-provided applications and supervisory functions. The I/O 
modules can be invoked by calling the iox_ subroutine to interface directly with the 
Multics I/O System when performing I/O operations. 

The information is organized into three sections. Section 1 contains a list of the 
subroutine repertoire, arranged functionally. Section 2 contains descriptions of the 
Multics subroutines arranged in alphabetical order. Section 3 contains the descriptions 
of the I/O modules, also arranged in alphabetical order. 



Significant Changes in AG93-05A 

The following subroutines are new and do not contain change bars: 



condition_ ocu_ 

datebin_ pascal_util_ 

enter_abs_request_ print_data_ 

find_bit_ rcp_ 

find_char_ reversion. 

heap_manager_ translate_bytes_to_hex9_ 



The following subroutines have been complete rewritten to document additional 
capabilities; therefore, they contain no change bars: 



check_star_name_ 
match_star_name_ 



The following subroutine was affected by the C software: 



cu_ 



The following entry points have been moved from the obsolete section to the active 
section: 



cu_$decode_entry_value 
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The following entry points have been moved from the active section to the obsolete 
section: 

ipc_$create_ev_chn 
ipc_$decl_event_call_chn 

The following entry points were accidentally left out of the manual for MR11.0: 

sort_items_$char 
sort_items_$f ixed_bin 
sort_items_$float_bin 
sort_items_$general • 
sort_items_$varying_char 

Extensive information was accidentally left out from the following I/O modules for 
MR11.0: 

tape_ansi_ 
tape_ibm_ 
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SECTION 1 

INTRODUCTION TO STANDARD SUBROUTINES 



The subroutines described in this document are the basic set included in the standard 
Multics system. Many of the functions described here are also provided as runtime 
features of Mul tics-supported programming languages. The user is encouraged to use 
language-related facilities wherever possible. 

This section presents the subroutine repertoire, organized by function into the 
following categories: 

Storage System, Pathname Manipulation 

Storage System, Access Control and Rings of Protection 

Storage System, Segment Manipulation 

Storage System, Directory Manipulation 

Storage System, Links and Search Facility 

Storage System, Multisegment Files (MSFS) 

Area Management 

Clock and Timer Procedures 

Command Environment Utility Procedures 

Subsystem Environment Utility Procedures 

Input/ Output System Procedures 

Error Handling Procedures 

Data Type Conversion Procedures 

Condition Mechanism 

Object Segment Manipulation 

Process Synchronization 

Resource Control Package (RCP) 

Run Units 

Data Management 

System Metering 

Miscellaneous Procedures 



Storage System, Pathname Manipulation 

absolute_pathname_ 

converts a relative or absolute pathname into an absolute pathname. 
change_def ault_wdir_ 

changes the user's current default working directory. 
change_wdir_ 

changes the user's current working directory. 
check_star_name_ 

verifies formation of entrynames according to star name rules. 
expand_pathname_ 

converts a relative or absolute pathname into a directory name and 
entryname. 
f ind_include_f ile_ 

locates an include file via system include file search files. 
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f ind_source_f ile_ 

finds a file given a pathname and an optional suffix. 
get_def ault_wdir_ 

returns pathname of user's current default working directory. 
get_equal_name_ 

constructs target name by substituting from entryname into equal name. 
get_pdir_ 

returns pathname of process directory. 
get_shortest_path_ 

shortens pathnames by replacing each directory level with the shortest 
name on the directory. 
get_wdir_ 

returns pathname of current working directory. 
hcs_$get_link_target 

returns the target pathname of a link. 
hcs_$f s_get_path_name 

returns pathname for a segment specified by segment number. 
hcs_$star_ 

returns storage system type and all names that match entryname 

according to star name rules. 
match_star_name_ 

compares entryname with starname. 
nd_handler_ 

resolves name duplication, 
pathname_ 

constructs pathnames and archive component pathnames. 
search_paths_ 

enables users to manipulate search lists and search segments, and to 
return directory names in which a specified entry can be found. 
suffixed_name_ 

aids in processing suffixed names. 



Storage System. Access Control and Rings of Protection 

aim_check_ 

determines relationship between two access attributes. 
aim_util_ 

manipulates AIM access classes and authorizations, 
check _gate_access_ 

differentiates between not finding the gate and not having access. 
compute_common_aim_ceiling_ 

computes the maximum athorization or access class which is in common 

between two Multics systems given the definitions of their AIM 

attributes. 
convert_aim_attributes_ 

converts representation of process' /segment's access authorization /class 

into character string of defined form. 
convert_authorization_ 

converts an authorization back and forth between its binary and 

character-string representation. 
copy_aci_ 

copies the ACL from one segment, MSF, or directory to another. 
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cross_ring_io_$allow_cross 

allows use of an I/O switch via cross_ring_ attachments from an outer 

ring. 
cu_$level_get 

obtains current ring validation level. 
cu_$level_set 

sets current ring validation level. 
cv_dir_mode_ 

converts a character string containing access modes for directories into a 
bit string used by the ACL entries. 
cv_mode_ 

converts a character string containing access modes for segments into a 
bit string used by the ACL entries. 
cv_userid_ 

converts a character string containing an abbreviated User_id into one 

containing all three components, 
f s_util_$add_acl_en tries 

used to add to the Access Control List of an entry, 
f s_util_$add_ex tended_acl_en tries 

used to add to the Extended Access Control List of standard entry, 
f s_util_$delete_acl_en tries 

deletes a member of an entry's Access Control List, 
f s_util_$get_ring_brackets 

returns the ring brackets of an entry, 
f s_util_$get_user_access_modes 

returns the user's effective access mode and extended access mode on an 

entry. 
fs_util_$list_acl 

list the components of an entry's Access Control List, 
f s_util_$list_extended_acl 

returns the contents of the Extended Access Control List of a standard 

entry. 
fs_util_$repiace_acl 

used to replaced Access Control List components for an entry, 
f s_util_$replace_extended_acl 

used to replace Extended Access Control List components for a standard 

entry. 

f s_util_$set_ring_brackets 

sets the ring brackets for an entry. 
get_authorization_ 

returns authorization value of the process. 
get_group_id_ 

returns access control name of current user. 
get_initial_ring_ 

obtains a process' initial ring number. 
get_max_authorization_ 

returns maximum authorization value of the process. 
get_privileges_ 

returns process' access privileges. 
get_process_authorization_ 

returns the process's current authorization. 
get_ring_ 

returns number of current protection ring. 
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get_system_aim_attributes_ 

returns a structure describing the AIM attributes defined on the host 

system. 
hcs_$add_acl_entries 

adds or changes ACL entries on a segment. 
hcs_$add_dir_acl_en tries 

adds or changes ACL entries on a directory. 
hcs_$add_dir_inacl_entries 

adds specified access modes to initial ACL for directories. 
hcs_$add_inacl_entries 

adds specified access modes to initial ACL for segments. 
hcs_$delete_acl_entries 

deletes all or part of an ACL on a segment 
hcs_$delete_dir_acl_entries 

deletes all or part of an ACL on a directory. 
hcs_$delete_dir_inacl_entries 

deletes specified entries from initial ACL for directories. 
hcs_$delete_inacl_en tries 

deletes specified entries from initial ACL for segments. 
hcs_$f s_get_mode 

returns access control mode for a given segment relative to the current 

validation level. 
hcs_$get_access_class 

returns access class for a directory. 
hcs_$get_access_class_seg 

returns access class for a segment. 
hcs_$get_dir_ring_brackets 

returns ring brackets for specified subdirectory. 
hcs_$get_ring_brackets 

returns ring brackets for specified segment. 
hcs_$get_user_ef f mode 

returns a user's effective access mode to a branch. 
hcs_$list_acl 

returns all or part of an ACL on a segment. 
hcs_$list_dir_acl 

returns all or part of an ACL on a directory. 
hcs_$list_dir_inacl 

returns all or part of initial ACL for directories. 
hcs_$list_inacl 

returns all or part of initial ACL for segments. 
hcs_$replace_acl 

replaces one ACL on a segment with another. 
hcs_$replace_dir_acl 

replaces one ACL on a directory with another. 
hcs_$replace_dir_inacl 

replaces initial ACL with user-provided one for directories. 
hcs_$replace_inacl 

replaces initial ACL with user-provided one for segments. 
hcs_$set_dir_ring_brackets 

sets ring brackets for specified directory. 
hcs_$set_ring_brackets 

sets ring brackets for specified segment. 
msf_manager_$acl_add 

adds the specified access modes to the ACL of the multisegment file. 
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msf_manager_$acl_delete 

deletes ACL entries from the ACL of a multisegment file. 
msf_manager_$acl_list 

returns the access control list (ACL) of a multisegment file. 
msf_manager_$acl_replace 

replaces the ACL of a multisegment file. 
read_allowed_ 

determines if AIM allows read operations on object given process' 

authorization and object's access class. 
read_wri te_allowed_ 

determines if AIM allows read /write operations on object given process' 

authorization and object's access class. 
ringO_get_ 

supplies name, segment number, and entry point information about ring 

0 segments. 
ring_zero_peek_ 

copies information out of an inner-ring segment. 
translate_aim_attributes_ 

translates the AIM attributes in an authorizatin or access class from one 

system's definition to another system's definition where possible. 
write_allowed_ 

determines if AIM allows write operations on object given process' 
authorization and object's access class. 



Storage System, Segment Manipulation 

adjust_bit_ccunt_ 

sets bit count of a segment to last nonzero character, 
archive. 

accesses, lists, or obtains information about archive components. 

delete_ 

deletes segments. 
dl_handler_ 

issues queries for situations involving deletion. 
dump_segment_ 

prints a dump formatted the same way as the dump_segment command, 
f ind_include_f ile_ 

locates an include file via system include file search rules. 
find_source_file_ 

finds a file given a pathname and an optional suffix. 
fs_util_$chname_file 

changes the name of an entry. 
fs_util_$copy 

used to copy an entry. 
fs_util_$delentry_file 

deletes the name of an entry, 
f s_util_$get_bit_count 

returns the number of useful bits in an entry, 
f s_util_$get_max_length 

returns the maximum length setting for an entry, 
f s_util_$get_switch 

returns the value of a storage system switch for an entry. 
fs_util_$get_type 

returns the type of a specified entry. 
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f s_util_$list_switches 

returns a list of switches supported by the entry type, 
f s_util_$list_switches_f or_type 

returns a list of switches for a particular type of entry, 
f s_util_$make_entry 

constructs an entry variable to a specified suffix support subroutine 

entry for a specified extended entry, 
f s_util_$make_entry_f or_ty pe 

constructs an entry variable to a specified suffix support subroutine 

entry for a specified extened entry, 
f s_util_$set_bit_count 

sets the number of bits considered useful for an entry, 
f s_util_$set_max_length 

sets the maximum length that a particular entry can be. 
f s_util_$set_switch 

sets the value of a storage system switch for an entry, 
f s_util_$suf f ix_inf o 

returns information about an entry's type, 
f s_util_$suf f ix_inf o_f or_type 

returns information about the characteristics of an entry that is of a 

given type. 
hcs_$append_branch 

creates a segment and initializes its ACL. 
hcs_$change_bc 

provides an indivisible method of changing the bitcount of a segment: 
hcs_$change_bc_seg 

provides an indivisible method of changing the bitcount of a segment. 
hcs_$chname_file 

changes the entryname on a specified entry. 
hcs_$chname_seg 

changes the entryname on a segment, given a pointer to the segment. 
hcs_$create_branch_ 

creates a segment, sets a number of attributes. 
hcs_$f s_get_path_name 

returns pathname for a segment specified by segment number. 
hcs_$f s_get_ref _name 

returns a reference name for a segment specified by segment number. 
hcs_$f s__get_seg„ptr 

returns a segment number for a segment specified by a reference name. 
hcs_$fs_move_file 

moves contents of one segment to another, given pathnames of the 
segments. 
hcs_$fs_move_seg 

moves contents of one segment to another, given pointers to the 

segments. 
hcs_$get_author 

returns author of segment. 
hcs_$get_bc_author 

returns bit count author of a segment. 
hcs_$get_max_length 

returns maximum length of segment in words, given directory name and 

entryname. 
hcs_$get_max_iength_seg 

returns maximum length of segment in words, given a pointer to a 

segment. 
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hcs_$get_saf ety_sw_seg 

returns safety switch value of segment. 
hcs_$get_uid_f ile 

returns the unique identifier of a storage system entry. 
hcs_$get_uid_seg 

returns the unique identifier associated with a segment. 
hcs_$initiate 

when given a pathname and a reference name, makes known the 
segment defined by the pathname initiates the given reference name, 
and increments the count of initiated reference names for the segment 
hcs_$initiate_count 

when given a pathname and a reference name, causes the segment 
defined by the pathname to be made known and the given reference 
name initiated. 
hcs_$make_entry 

makes a segment known and returns the value of a specified entry 
point. 
hcs_$make_ptr 

makes a segment known and returns a pointer to a specified entry 
point 
hcs_$make_seg 

creates a new segment, makes it known to the process and returns a 
pointer. 
hcs_$set_bc 

sets the bit count and bit count author of a segment 
hcs_$set_bc_seg 

sets the bit count and bit count author of a segment, given a pointer 

to the segment 
hcs_$set_entry_bound' 

sets entry point bound of segment. 
hcs_$set_entry_bound_seg 

sets entry point bound of segment. 
hcs_$set_max_length 

sets maximum length of segment 
hcs_$set_max_length_seg 

sets maximum length of segment 
hcs_$set_safety_sw 

sets safety switch of segment 
hcs_$set_saf ety_sw_seg 

sets safety switch of segment 
hcs_$status_ 

returns various items of information about a specified directory entry. 
hcs_$status_long 

returns most user-accessible information about an entry. 
hcs_$status_minf 

returns the bit count and entry type, given the name of a directory and 
an entry. 
hcs_$status_mins 

returns the bit count and entry type, given a pointer to the segment 
hcs_$truncate_file 

truncates a file or segment to a given length, given a pathname. 
hcs_$truncate_seg 

truncates a file or segment to a given length, given a pointer. 
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initiate_file_ 

contains entry points for making a segment or archive component 

known with a null reference name. 
mhcs_$get_seg_usage 

returns the number of page faults taken on a segment since its creation. 
nd_handler_ 

resolves name duplication. 
pascal_util_ 

provides interfaces for establishing and removing an on unit for the 
current procedure. 

qedx_ 

provides a subroutine interface to the Multics qedx Editor for use by 
subsystems wishing to edit arbitrary strings of ASCII text 
sort_seg_ 

provides entry points for sorting segments and character strings. 

term_ 

removes a segment from the address space, unsnapping any subroutine 
linkage to it. 
terminate_file_ 

performs common operations often necessary after a program finishes 

using a segment 
tssi_$clean_up_segment 

is used by cleanup procedures in the translator. 
tssi_$f inish_segment 

makes a segment unknown, sets bit count and ACL. 
tssi_$get_segment 

prepares a segment for use as output from the translator. 



Storage System, Directory Manipulation 

change_def ault_wdir_ 

changes the user's current default working directory. 
change_wdir_ 

changes user's current working directory. 
copy_dir_ 

copies a subtree from one point in the hierarchy to another. 

delete_ 

deletes directories. 
dl_handler_ 

issues queries for situations involving deletion, 
f s_util_$chname_f ile 

changes the name of an entry. 
fs_util_$delentry_file 

deletes the name of an entry, 
f s_util_$get_bit_count 

returns the number of useful bits in an entry, 
f s_util_$get_switch 

returns the value of a storage system switch for an entry. 
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fs_util_$get_type 

returns the type of a specified entry, 
f s_util_$list_switches 

returns a list of switches supported by the entry type, 
f s_util_$list_switches_f or_type 

returns a list of switches for a particular type of entry, 
f s_util_$make_entry 

constructs an entry variable to a specified suffix support subroutine 

entry for a specified extended entry. 



11/86 



1-8.1 



AG93-05A 



This page intentionally left blank. 



11/86 AG93-05A 



f s_util_$make_entry_f or_type 

constructs an entry variable to a specified suffix support subroutine 

entry for a specified extened entry, 
f s_util_$set_bit_count 

sets the number of bits considered useful for an entry, 
f s_util_$set_switch 

sets the value of a storage system switch for an entry, 
f s_util_$suf f ix_inf o 

returns information about an entry's type, 
f s_util_$suf f ix_inf o_f or_type 

returns information about the characteristics of an entry that is of a 

given type. 
get_def ault_wdir_ 

returns pathname of user's current default working directory. 
get_pdir_ 

returns pathname of process directory. 
get_wdir_ 

returns pathname of current working directory. 
hcs_$append_branchx 

creates a directory and initializes its ACL. 
hcs_$append_link 

creates a link to a directory. 
hcs_$chname_file 

changes the entryname on a specified entry. 
hcs_$create_branch_ 

creates a directory, sets a number of attributes. 
hcs_$get_author 

returns author of a directory. 
hcs_$get_bc_author 

returns bit count author of a directory. 
hcs_$get_uid_file 

returns the unique identifier of a storage system entry. 
hcs_$get_saf ety_sw 

returns safety switch value of directory. 
hcs_$quota_move 

moves all or part of quota between two directories. 
hcs_$quota_read 

returns record quota and accounting information for directory. 
hcs_$set_bc 

sets multisegment file indicator for a directory. 
hcs_$set_saf ety_sw 

sets safety switch of directory. 
hcs_$status_ 

returns various items of information about a specified directory entry. 
hcs_$status_long 

returns most user-accessible information about an entry. 
hcs_$status_minf 

returns the bit count and entry type, given the name of a directory and 
an entry. 
list_dir_info_ 

lists the values in an entry in a directory information segment. 

mdc_ 

provides entrypoints for master directory manipulation. 
nd_handler_ 

resolves name duplication. 
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sweep_disk_ 

walks a given subroutine over a subtree of the directory heirarchy. 



Storage System, Links and Search Facility 

cv_entry_ 

converts a virtual entry to an entry value. 

cv_ptr_ 

converts a virtual pointer to a pointer value. 

delete_ 

unlinks links. 
get_entry_name_ 

returns associated name of externally defined location or entry point in 

segment, 
get_external_variable_ 

obtains the location and size of an external variable. 
hcs_$append_link 

creates a link to a directory. 
hcs_$fs _get_refname 

returns a reference name for a segment specified by segment number. 
hcs_$fs _get_seg_ptr 

returns a segment number for a segment specified by a reference name. 
hcs_$get_author 

returns author of a link. 
hcs_$get_search_rules 

returns user's current search rules. 
hcs_$get_system_search_rules 

prints site-defined search rule keywords. 
hcs_$initiate_search_rules 

allows user to specify search rules. 
hcs_$make_entry 

makes a segment known and returns the value of a specified entry 
point. 
hcs_$make_plr 

makes a segment known and returns a pointer to a specified entry 
point. 
search_paths_ 

enables users to manipulate search lists and search segments, and to 
return directory names in which a specified entry can be found. 
set_ext_variable_ 

allows the caller to look up an external variable by name. 



Storage System, Multisegment Files (MSFs) 
msf_manager_ 

provides the means for multisegment files to create, access, and delete 

components, truncate the file and control access. 
tssi_$clean_up_f ile 

is used by cleanup procedures in the translator, 
tssi Sfinish file 

makes a MSF unknown, sets bit count and ACL. 
tssi_$get_file 

prepares a MSF for use as output from the translator. 
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Area Management 

area_info_ 

returns information about an area. 
cu_$grow_stack_f rame 

allows caller to allocate temporary storage. 
cu_$shrink_stack_f rame 

allows caller to deallocate temporary storage. 
define_area_ 

initializes a region of storage as an area. 
get_external_variable_ 

obtains the location and size of an external variable. 
get_system_f ree_area_ 

returns pointer to system free area for calling ring. 
get_temp_segmen t_ 

acquires a single temporary segment in the process directory. 
get_temp_segments_ 

acquires temporary segments in the process directory. 
release_area_ 

cleans up an area. 
release_temp_segment_ 

returns the temporary segment acquired by get_temp_segment_ to the 

free pool. 
release_temp_segments_ 

returns temporary segments to the free pool. 
set_ext_variable_ 

allows the caller to look up an external variable by name. 
ssu_$get_area 

obtains an area for use by a subsystem invocation. 
ssu_$get_temp_segmen t 

obtains a temporary segment for use by a subsystem invocation. 
ssu_$release_area 

releases an area previously obtained by a call to ssu_$get_area. 
ssu_$release„temp_segment 

releases a temporary segment previously acquired by a call to 

ssu_$ get_temp_segmen t. 
translator_temp_ 

provides a temporary storage management facility for translators. 

value_ 

reads and maintains value segments containing name-value pairs across 
process boundaries. 

Clock and Timer Procedures 

clock_ 

reads the system clock. 
convert_date_to_binary_ 

converts an ASCII string to binary time. 
cpu_time_and_paging_ 

returns virtual CPU time used and paging activity of the process. 
cv_fstime_ 

returns a Multics clock value. 
date_time_ 

converts binary time to an ASCII string. 



1-11 



AG93-05 



decode_clock_value_ 

converts a binary time value into an ASCII string. 
encode_clock_value_ 

converts a month, day, year, hour, minute, second, microsecond, and 

time zone into a system clock reading. 
hcs_$get_process_usage 

retrieves system resource usage information. 
request_id_ 

used by the absentee facility, I/O daemons, and other queue-driven 
facilities. 
timer_manager_ 

allows user process interruption after specified amount of CPU or 

real-time passes. 
total_cpu_time_ 

returns total CPU time used by this process. 
virtual_cpu_time_ 

returns virtual CPU time used by this process. 



Command Environment Utility Procedures 

abbrev_ 

subroutine interface to the abbrev command. 

ask_ 

flexible terminal-input facility for numbers and strings. 
command_query_ 

asks questions. 
cu_$af_arg_count 

returns to caller number of arguments passed by its caller. 
cu_$af_arg_count_rel 

same as hcs_$af_arg_count but for any argument list. 
cu_$af_arg_ptr 

returns a pointer to the character-string argument specified by the 

argument number. 
cu_$af_arg_ptr_rel 

permits referencing of arguments in any specified argument hst. 
cu_$af_return_arg 

makes available the return argument of an active function. 
cu_$af_return_arg_rel 

same as hcs_$af_return_arg but for any argument list. 
cu_$arg_count 

returns number of arguments supplied to the called procedure. 
cu_$arg_list_ptr 

returns a PL /I pointer to the argument list of its caller. 
cu_$arg_ptr 

returns a pointer to a specified argument in current argument list. 
cu_$arg_ptr_rel 

permits referencing of arguments in any specified argument list. 
cu_$caller_ptr 

allows a routine to obtain a pointer to its caller. 

cu_$cp 

calls the command processor to execute a command line, 
c u_$ e v ai uate_ac ti ve_str in g 

expands an active string. 
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cu_$get_command_processor 

returns entry value of procedure invoked by cu_$cp. 
cu_$get_evaluate_active_string 

returns entry value of procedure currently being invoked by call to 

cu_$evaluate_active_string. 
cu_$get_ready_mode 

returns value of static ready mode. 
cu_$get_ready_procedure 

returns entry value of ready procedure. 
cu_$ready_proc 

used to call ready procedure. 
cu_$reset_command_processor 

resets procedure invoked by calls to cu_$cp. 
cu_$reset_evaluate_active_string 

resets procedure invoked by calls to cu_$evaluate_active_string. 
cu_$reset_ready_procedure 

resets procedure invoked by calls to cu_$ready_proc. 
cu_$set_command_processor 

allows a subsystem developer to replace the standard command processor 

with a different procedure. 
cu_$set_evaluate_active_string 

allows a subsystem developer to replace the standard active string 

evaluator with a different procedure. 
cu_$set_ready_mode 

returns value of internal static ready flags. 
cu_$set_ready_procedure 

allows user to change his ready procedure. 
cu_$stack_frame 

returns a pointer to the stack frame of its caller. 
cu_$stack_f rame_size 

returns the size in words of the stack frame of the caller. 
decode„descriptor_ 

extracts information from argument descriptors. 
find_bit_ 

performs common bit string search operations. 
find_char_ 

performs the function of the PL/ 1 search and verify builtin functions. 
get_process_id_ 

returns identification of current process. 
get_temp_segment_ 

acquires a single temporary segment in the process directory. 
get_temp_segments_ 

acquires temporary segments in the process directory. 
hcs_$history_regs_get 

returns current state of per-process history register switch. 
hcs_$nistory_regs_set 

controls state of per-process history register switch. 
lex_string_ 

parses ASCII character strings. 
read_password_ 

reads user's password from the terminal. 
release_temp_segment_ 

returns the temporary segment acquired by get_temp_segment_ to the 

free pool. 
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release_temp_segments_ 

returns temporary segments to the free pool. 
requote_string_ 

doubles all quotes within a character string and returns the result 
enclosed in quotes. 
search_paths_ 

enables users to manipulate search lists and search segments, and to 
return directory names in which a specified entry can be found. 
terminate_process_ 

terminates the process in which it is called. 



Subsystem Environment Utility Procedures 
qedx_ 

provides a subroutine interface to the Multics qedx Editor for use by 
subsystems wishing to edit arbitrary strings of ASCII text. 
search_paths_ 

enables users to manipulate search lists and search segments, and to 
return directory names in which a specified entry can be found. 
ssu_$abort_line 

prints an error message and aborts the execution of the current 

subsystem request line. 
ssu_$abort_subsystem 

aborts the current invocation of a subsystem, optionally printing an 

error message. 
ssu_$add_dir_inf o 

adds a new directory to the list of info directories being searched by 

this subsystem invocation. 
ssu_$add_request_table 

adds a new request table to the list of request tables being searched by 

this subsystem invocation. 

ssu_$apply_request_util 

a utility procedure for implementing subsystem "apply" requests. 
ssu_$arg_count 

determines how many arguments a subsystem request received. 
ssu_$arg_list_ptr 

gets a pointer to a subsystem request's argument list. 
ssu_$arg_ptr 

is used by a procedure implementing a subsystem request to access its 

arguments. 
ssu_$create_invocation 

creates an invocation of a subsystem. 
ssu_$deiete_inf o_dir 

deletes a directory from the list of info directories being searched. 
ssu_$delete_request_table 

deletes a request table from the list of tables being searched. 
ssu_$destroy_invocation 

destroys a subsystem invocation. 
ssu_$evaluate_active_string 

interprets a single active request string in a subsystem. 
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ssu_$execute_line 

interprets a single request line. 
ssu_$execute_start_up 

executes the current subsystem's start_up exec_com. 
ssu_$execute_string 

executes a request string, usually expressed as an in-line constant or 
character string variable. 
ssu_$get_area 

obtains an area for use by a subsystem invocation. 
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ssu_$get_debug_mode 

gets the current state of subsystem debug mode. 
ssu_$get_def ault_procedure 

gets the default value for a replaceable procedure value. 
ssu_$get_def ault_rp_options 

returns the default request processor options for the current subsystem. 
ssu_$get_ec_search_list 

returns the name of the search list currently being used to find 

subsystem exec_com files. 
ssu_$get_ec_subsystem_ptr 

returns the pointer currently used to implement the "referencing_dir" 

rule in the search list for subsystem exec_coms. 
ssu_$get_ec_suf f ix 

returns the suffix currently being used for subsystem exec_com files. 
ssu_$get_inf o_ptr 

gets the info_ptr for this subsystem invocation. 
ssu_$get_in vocation_coun t 

determines the invocation index of the current subsystem invocation. 
ssu_$get_level_n_sci_ptr 

examines the state of other invocations of the subsystem by returning 

pointers for the other invocation. 
ssu_$get_prev_sci_ptr 

examines the state of other invocations of the subsystem by returning 

pointers for the immediately previous invocation. 
ssu_$get_procedure 

gets the current value for a replaceable procedure value in the specified 

subsystem invocation. 
ssu_$get_prompt 

gets the string currently being used as a prompt. 
ssu_$get_prompt_mode 

gets the current state of the prompting mode. 
ssu_$get_ready_mode 

determines the current state of ready processing. 
ssu_$get_request_name 

determines the primary name of the subsystem request currently being 

executed. 

ssu_$get_reqeust_processor_options 

returns the request processor options presently in effect for the current 

subsystem. 
ssu_$get_subsystem_and_request_name 

acquires a string identifying the subsystem and the current request. 
ssu_$get_subsystem_name 

determines the name of the subsystem owning the specified invocation. 
ssu_$get_subsystem_version 

determines the version number of the subsystem. 
ssu_$get_temp_segment 

obtains a temporary segment for use by the current subsystem 

invocation. 
ssu_$list_inf o_dirs 

lists the info directories currently in use by this subsystem invocation. 
ssu_$list_request_tables 

lists the request tables currently in use by this subsystem invocation. 
ssu_$listen 

implements the subsystem listener. 
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ssu_$print_blast 

prints a "blast" message announcing a new version of the subsystem. 
ssu_$print_message 

prints informational, warning, or nonfatal error messages. 
ssu_$record_usage 

makes an entry in the usage segment to record a use of the subsystem. 
ssu_$release_area 

releases an area previously obtained by a call to ssu_$get_area. 
ssu_$release_temp_segment 

releases a temporary segment previously obtained by a call to 

ssu_$get_temp_segment. 
ssu_$reset_procedure 

resets a replaceable procedure in the current subsystem to its default 

value. 

ssu_$reset_request_processor options 

resets the request processor options presently in effect to their default 

values. 
ssu_$return_arg 

is used by a subsystem request procedure to determine whether it has 

been invoked as an active request. 
ssu_$set_debug_mode 

sets debug mode for the subsystem. 
ssu_$set_ec_search_list 

sets the name of the search list used to find subsystem exec_com files. 
ssu_$set_ec_subsy5teni_ptr 

sets the directory used to implement the "referencing_dir" rule in the 

search list for subsystem exec_coms. 
ssu_$set_ec_suf f ix 

sets the suffix for subsystem exec_com files. 
ssu_$set_inf o_dirs 

sets the list of info directories searched by this subsystem invocation. 
ssu_$set_info_ptr 

sets the info_ptr for this subsystem invocation. 
ssu_$set_procedure 

sets the current value of a replaceable procedure in this subsystem 

invocation. 
ssu_$set_prompt 

sets the prompt string for the subsystem. 
ssu_$set_prompt_mode 

sets the prompting mode for the subsystem. 
ssu_$set_ready_mode 

turns ready message processing in the subsystem listener on or off. 
ssu_$set_request_processor_options 

changes the request processor options presently in effect. 
ssu_$set_request_tables 

sets the list of request tables searched by the subsystem. 
ssu_$standalone_invocation 

creates a "standalone" subsystem invocation for use by Multics 

commands /active functions which can also be used as subsystem 

requests. 
sort_seg_ 

provides entry points for sorting segments and character strings. 
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Input/Output System Procedures 
cb_menu_ 

allows a COBOL program to use the Multics menu facility (menu_). 
cb_window_ 

is the basic video interface subroutine used by COBOL to 

create/destroy/change windows. 
convert_dial_message_ 

controls dialed terminals. 
cross_ring_io_$aiiow_cross 

allows use of an I/O switch via cross_ring_ attachments from an outer 

ring. 
dial_manager_ 

interfaces to the answering service dial facility. 
display_f ile_value_ 

outputs information about a file on a user-supplied switch. 

dprint_ 

adds print, punch or plot requests to the specified queue. 
find_partition_ 

obtains information about a disk partition located on some mounted 

storage system disk, 
f ormat_document_ 

fills and adjusts text. 
ft_menu_ 

allows a FORTRAN program to use the Multics menu facility (menu_). 
ft_window_ 

is the basic video interface subroutine to be used by FORTRAN to 

create/destroy/change windows. 
get_line_length_ 

returns the line length of an I/O switch. 
hcs_$force_write 

writes pages from memory to disk. 
hphcs_$read_partition 

reads words of data from a specified disk partition on some mounted 

physical storage disk. 
hphcs_$write_partition 

writes words of data into a specified disk partition on some mounted 

physical storage-system disk. 

ioa_ 

produces formatted printed output 
iod_info_ 

extracts information from the I/O daemon tables for commands and 
subroutines submitting I/O daemon requests. 

iox_ 

interfaces with the Multics I/O system. 

menu_ 

provides menu display and selection services. 
mode_string_ 

manipulates mode strings; can parse, analyze, and create them. 
phcs_$read_disk_label 

reads the label of a storage-system disk volume. 

pll_io_ 

extracts information about PL/ 1 files. 
shcs_$set_f orce_write_limit 

fixes limit on number of pages to be written to disk. 
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timed_io_ 

performs I/O operations and returns an error code if it cannot 
complete its operation within the time specified. 
ttt_info_ 

extracts information from the terminal type table (TTT). 
vfile_status_ 

returns information about a storage system file supported by the vfile_ 
I/O module. 
video_data_ 

is a data segment containing information about the video system. 
video_utils_ 

provides interfaces for activating and de-activating the video system, 
window. 

provides a terminal interface to video terminal operations. 



Error Handling Procedures 

active_fnc_err_ 

prints formatted error message and signals active_function_error condition. 
com_err_ 

prints a standard status message for command errors. 
command_query_ 

asks questions, 
condition. 

establishes a handler for a condition in the calling block activation. 
convert_status_code_ 

returns short and long status messages for given status code. 

cu_$cl 

reenters command level. 
cu_$get_el_intermediary 

returns procedure invoked by cu_$cl. 
cu_$reset_cl_intermediary 

resets procedure invoked by calls to cu_$cl. 
cu_$set_cl_intermediary 

sets procedure invoked by cu_$cl. 
cv_error_ 

converts an error name to an error code. 
dl_handler_ 

issues queries for situations involving deletion. 
find_bit_ 

performs common bit string search operations. 
find_char_ 

performs the function of the PL/ 1 search and verify builtin functions. 
hcs_$get_page_trace 

retrieves trace of process' page faults from the supervisor. 
lex_error_ 

generates compiler-style error messages. 
nd_handler_ 

resolves name duplication. 
print_cobol_error_ 

prints error messages produced by COBOL programs, 
reversion 

causes the handler currently established for the given condition in the 
calling block activation to be disestablished. 



11/86 



1-18 



AG93-05A 



ssu_$abort_line 

prints an error message and aborts the execution of the current 

subsystem request line. 
ssu_$abort_subsystem 

aborts the current invocation of a subsystem, optionally printing an 

error message. 
sub_err_ 

reports errors detected by other subroutines. 



Data Type Conversion Procedures 

add_bit_offset_ • 

returns pointer to bit relative to bit referenced by input pointer. 
add_char_offset_ 

returns pointer to character relative to character referenced by input 

pointer. 
arithmetic_to_ascii_ 

formats any arithmetic value. 
ascii_to_bcd_ 

performs isomorphic (one-to-one reversible) conversion from ASCII to 
BCD. 
ascii_to_ebcdic_ 

performs conversion from ASCII to EBCDIC. 

assign_ 

assigns specified source value to specified target performing required 
conversion. 
bcd_to_ascii 

performs isomorphic (one-to-one reversible) conversion from BCD to 
ASCII. 
bit_offset_ 

returns bit offset of pointer. 

/•Hot rvffcAt 
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. returns character offset of pointer. 
char_to_numeric_ 

converts user-supplied string to a numeric type. 
convert_date_to_binary_ 

converts ASCII string to binary clock reading. 
cv_bin_ 

converts binary representation of an integer to 12-character ASCII 
string. 
cv_dec_ 

converts an ASCII representation of a decimal integer to fixed bin(35). 
cv_dec_check_ 

same as cv_dec_ except that a code is returned indicating the possibility 
of a conversion error. 
cv„dir__mode_ 

converts a character string containing access modes for directories into a 
bit string used by the ACL entries. 
cv_mode_ 

converts a character string containing access modes for segments into a 
bit string used by the ACL entries. 
cv_entry_ 

converts a virtual entry to an entry value. 
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cv_float_ 

converts an ASCII representation of a floating point number and returns 
a single precision floating point representatio5 
cv_float_double_ 

converts an ASCII representation of a floating point number and returns 
a double precision floating point representation. 
cv_hex_ 

converts an ASCII representation of a hexadecimal integer to fixed 
binary (35). 
cv_hex_check_ 

same as cv_hex_ except that a code is returned indicating the possibility 
of a conversion error. 

cv_oct_ 

converts an ASCII representation of an octal integer to fixed binary 
(35) of an octal integer. 
cv_oct_check_ 

same as cv_oct_ except that a code is returned indicating the possibility 
of a conversion error. 

cv_ptr_ 

converts a virtual pointer to a pointer value. 
date_time_ 

converts a clock reading to an ASCII string. 
decode_clock_value_ 

converts a binary time value into an ASCII string. 
ebcdic_to_ascii_ 

performs conversion from EBCDIC to ASCII. 
encode_clock_value_ 

converts a month, day, year, hour, minute, second, microsecond, and 

time zone into a system clock reading. 
find_bit_ 

performs common bit string search operations. 
find_char_ 

performs the function of the PL/ 1 search and verify builtin functions. 
lex_string_ 

parses ASCII character strings. 

mlr_ 

moves a character string by copying the characters from left to right. 

mrl 

moves a character string by copying the characters from right to left. 

mvt_ 

provides for translation of character strings using translations which are 

not known at compile time. 
numeric_to_ascii_ 

formats a real decimal floating-point number. 
numeric_to_ascii_base_ 

formats a real decimal floating-point number based in any number 

system from 2 to 16. 
parse_channel_name_ 

parses a character string that is intended to be an IOM channel 

number. 
parse_file_ 

parses ASCII text into symbols and break characters, 
pfint_data_ 

formats and prints the output of a PL/I put data statement. 



11/86 



1-20 



AG93-05A 



set_bit_offset_ 

returns pointer to specified bit in segment referenced by input pointer. 
set_char_offset_ 

returns pointer to specified character in segment referenced by input 
pointer. 
sort_seg_ 

provides entry points for sorting segments and character strings. 
translate_by tes_to_hex9_ 

translates a bit string to a character string containing the hexadecimal 

representation of the bits. 
unique_bits_ 

returns a unique bit string. 
unique_chars_ 

converts a unique bit string to a unique character string. 
valid_decimal_ 

checks decimal data for validity. 



Condition Mechanism 

add_epilogue_handler_ 

adds to the list of handlers called when a process or run unit is 

terminated, 
condition. 

establishes a handler for a condition in the calling block activation. 
condition_interpreter_ 

prints formatted error message for most conditions. 
continue_to_signal_ 

enables on unit that cannot completely handle condition to tell signalling 

program to search stack for other on units for condition. 
exponent_control_ 

provides control over system's behavior in event of computational 

overflow or underflow, 
f ind_condition_f rame_ 

returns a pointer to the most recent condition frame, 
f ind_condition_inf o_ 

returns information about condition when signal occurs. 
hcs_$get_exponent_control 

returns flag settings that control handling of overflow and underflow 

conditions. 
hcs_$set_exponent_control 

changes flag settings that control handling of overflow and underflow 

conditions. 
heap_manager_$push_heap_level 

creates a new heap level, allocates the heap header and chains the 

previous heap to the current heap. 
heap_manager_$pop_heap_level 

resets the heap to the previous level freeing the old heap and any 

variables allocated therein. 
heap_manager_$get_heap_header 

returns a pointer to the heap header for the specified execution level. 
heap_manager_$get_heap_level 

returns the current execution level from the current heap header. 
heap_manager_$get_heap_area 

returns a pointer to the heap area for the specified level. 
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prepare_mc_restart_ 

checks machine conditions for restartability, and permits modifications to 
them for user changes to process execution before condition handler 
returns. 

sct_manager_ 

manipulates the System Condition Table; can set a static handler, get a 
pointer to one, and call one. 

signal_ 

signals occurrence of given condition. 
sus_signal_handler_ 

is the static condition handler for the sus_ condition. 
unwinder_ 

performs nonlocal goto on Multics stack. 



Object Segment Manipulation 

component_inf o_ 

returns information about a component of a bound segment. 
create_data_segmen t_ 

creates a standard object segment from PL /I data. 
decode_def ini tion_ 

returns information about a definition in the object segment. 
get_bound_seg_inf o_ 

supplies structural information about a bound segment. 
gei_definition_ 

returns pointer to specified definition within an object segment 
get_entry_arg_descs_ 

returns information about the calling sequence of an entry point. 
get_entry_point_dcl_ 

returns attributes needed to construct a PL/ 1 declare statement. 
object_info_ 

prints structural and identifying information extracted from object 
segment. 

stu_ 

retrieves information from the runtime symbol table section of an 
object segment. 
translator_info_ 

supplies source segment information for use by translators building 
object segments. 

tssi_ 

simplifies use of storage system by language translators. 



Process Synchronization 

create_ips_mask_ 

returns a bit string that can be used to disable specified ips interrupts. 
get_lock_id_ 

returns a 36-bit unique identifier to be used in setting locks. 
hcs_$get_ips_mask 

returns the value of the current ips mask, 
hcs . J>reset_ips_mask 

replaces the entire ips mask with a specified ips mask. 
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hcs_$set_ips_mask 

replaces the entire ips mask with a specified ips mask. 
hcs_$validate_processid 

determines whether a 36-bit quantity is the unique identifier of a 

process which is currently active on the system. 
hcs_$wakeup 

sends interprocess communication wakeup to blocked process over 
specified event channel. 
hphcs_$ips_wakeup 

sends a specified IPS signal to a specified process. 

ipc_ 

user interface to Multics interprocess communication facility. 
set_lock_ 

allows multiple processes to synchronize their use of shared data. 



Resource Control Package (RCP) 

cv_rcp_attributes_ 

manipulates RCP resource attribute specifications and descriptions. 
interpret_resource_desc_ 

displays selected contents of RCP resource description. 
resource_control_ 

provides interface to Multics resource control facility. 
resource_info_ 

returns selected information about RCP resource types defined on the 
system. 



Run Units 

add_epilogue_handler_ 

adds to the list of handlers called when a process or run unit is 

terminated. 
execute_epilogue_ 

cleans up language I/O buffers in conjunction with run units. 

run_ 

sets up special environment for executing programs. 
rmu$environment_inf o 

returns information about run environment. 



Data Management 

bef ore_journal_manager_ 

provides the means to manipulate and obtain information about before 

journals. 
file_manager_ 

interface between the data storage and retrieval services of data 
management and Multics file access and control mechanisms. 
transaction_manager_ 

begins and ends transactions on behalf of users, returns information 
about transactions, and recovers transactions after system failure. 
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System Metering 



meter_gate_ 

returns data about specific gate entries to the caller. 
spg_util_ 

collects metering information from the Multics supervisor and subtracts 
it from the previous sample taken. 
spg_ring_0_inf o_ 

returns information about the virtual CPU time spend in the three main 
gates into ring zero. 



Miscellaneous Procedures 
abbrev_ 

subroutine interface to the abbrev command. 
get_ec_version_ 

returns the version number of an exec_com. 

hash_ 

maintains a hash table; contains entry points that initialize a hash table 
and insert, delete, and search for entries in the table. 
hash_index_ 

computes the value of a hash function. 

help_ 

locates info segs. 

qedx_ 

provides a subroutine interface to the Multics qedx Editor for use by 
subsystems wishing to edit arbitrary strings of ASCII text. 
random_ 

returns random numbers. 

rehash_ 

reformats a hash table of the form maintained by hash_ into a 
different size. 
send_mail_ 

sends a message and an optional wakeup to a user. 
send_message_ 

sends an interactive message to be received by the message facility. 
set_ext_variable_ 

allows the caller to look up an external variable by name. 
sort_items_ 

provides a general sorting facility. 
sort_items_indirect_ 

provides a facility for sorting a group of data items. 
sort_seg_ 

provides entry points for sorting segments and character strings. 
sweep_disk_ 

walks a given subroutine over a subtree of the directory hierarchy. 
system_info_ 

provides user with information on system parameters. 



11/86 



1-24 



AG93-05A 



teco_get_macro_ 

called by teco to search for an external macro. 
ttt_info_ 

extracts information from the terminal type table (TTT). 
user_info_ 

returns miscellaneous information about the current user, 

value_ 

reads and maintains value segments containing name-value pairs. 
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SECTION 2 
SUBROUTINE DESCRIPTIONS 



This section contains descriptions of the Multics subroutines and functions, presented 
in alphabetic order. The term "subroutine" in this section refers alike to subroutines 
and functions, where the difference is not important. The individual descriptions 
specify for each name whether it represents a subroutine or a function. Each 
description contains the name of the subroutine, discusses the purpose of the 
subroutine, lists the entry points, and describes the correct usage for each entry point. 
Notes and examples are included when deemed necessary for clarity. The discussion 
below briefly describes the context of the various divisions of the subroutine 
descriptions. 

NAME 

The "Name" heading shows the acceptable name by which the subroutine is called. 
The name is usually followed by a discussion of the purpose and function of the 
subroutine and the results that may be expected from calling it. 

ENTRY 

Each "Entry" heading lists an entry point of the subroutine call. This heading may or 
may not appear in a subroutine description; its use is entirely dependent upon the 
purpose and function of the individual subroutine. 

USAGE 

The "Usage" section contains a sample declare statement and a sample call (or asign) 
statement expressed in PL/I notation. It is to be assumed, unless otherwise specified, 
that arguments are required. 

ARGUMENTS 

Arguments described under the "Usage" heading are explained in this section. 
Arguments that must be defined before calling the subroutine are identified as Input; 
those arguments defined by the subroutine are identified as Output. 

NOTES 

Comments or clarifications that relate to the subroutine as a whole (or to an entry 
point) are given under the "Notes" heading. 

OTHER HEADINGS 

Additional headings are used to introduce specific subject matter. Additional headings 
used include "Examples" (for sample. code fragments) and "Structure" (used to define 
the structure of an include file). 
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STATUS CODES 



The standard status codes returned by the subroutines are further identified, when 
appropriate, as either storage system or I/O system. Certain codes have been included 
in the individual subroutine description if they have a special meaning in the context 
of that subroutine; no attempt is made to show all of the possible error codes. 

A list of system status codes and their meanings appears in the Programmer's 
Reference Manual. The reader should not assume that the code(s) given in a particular 
subroutine description are the only ones that can be returned. Since a code of 0 
means that the given operation was executed successfully, this value is omitted from 
the list of possible codes under "code" in the "where" list. 

TREATMENT OF LINKS 

Generally, whenever the programmer references a link, the subroutine action is 
performed on the entry pointed to by the link. If this is the case, the only way the 
programmer can have the action performed on the link itself is if the subroutine has 
a chase switch and he sets the chase switch to zero. 
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Name: abbrev 

The abbrev_ subroutine provides a means of expanding abbreviations in command lines 
and changing data in and extracting data from the profile segments used by the 
abbrev command. All of the features of the command itself are available and a 
simple expand entry point is provided for returning expanded command lines. 

The main entry point is used to expand and execute a command line. The command 
line can be an abbrev request line, as recognized by the abbrev command documented 
in the Commands Manual. An abbrev request line can be used to add and delete 
abbreviations and change the modes of operation of abbrev. The abbrev command 
need not be invoked in the process before the abbrev_ subroutine can be called. 

USAGE 

declare abbrev_ entry (ptr, fixed bin(21), fixed bin (35)); 

call abbrev_ (line_ptr, line_len, code); 

ARGUMENTS 

line_ptr 

is a pointer to a character string to be interpreted as a command line or an 
abbrev request line. (Input) 

line_len 

is the number of characters in the input line. (Input) 

code 

is a standard status code returned by the command processor. (Output) 



Entry: abbrev (expanded line 

This entry point returns an expanded version of an input string. See the description 
of the abbrev command for a discussion of abbrev expansion. 

USAGE 

declare abbrev__$expanded_l i ne entry (ptr, fixed bin(21), ptr, 
fixed bin (21), ptr, fixed bin (35)); 

call abbrev_$expanded_l i ne (in_ptr, in_len, space_ptr, space_len, 
out_ptr , out_l en) ; 
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abbrev_ abbrev 



ARGUMENTS 
in_ptr 

is a pointer to a character string to be expanded. (Input) 
in_len 

is the number of characters in the input string. (Input) 
space_ptr 

is a pointer to a work space where the expanded character string can be placed. 
(Input) 

space_len 

is the number of characters available in the work space. (Input) 
out_ptr 

points to the expanded string. (Output) 
out_len 

is the number of characters in the expanded string. (Output) 
NOTES 

If the length of the expanded string exceeds the length of the work space provided, 
the expanded line is allocated in the system free area (see the get_system_free_area_ 
subroutine), It is the user's responsibility to free this storage when it is no longer 
needed. 

The space_ptr pointer should not point to the same string as in_ptr since expansion is 
done directly into the work space. 

Entry: abbrev Sset cp 

This entry point sets up a different command processor to be called by the abbrev_ 
subroutine after a command line is expanded. Its argument is an entry. If the first 
pointer in the entry is null, the command processor to be called is command_processor_. 

USAGE 

declare abbrev_$set_cp entry (entry); 
call abbrev_$set_cp (cp_entry) ; 
ARGUMENTS 

cp_entry 

is a command processor entry point. 
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EXAMPLES 
The code: 

chars = !i .a abi " jj char_string; 

call abbrev_ (addr (chars), length (chars), code); 

sets up abl as an abbreviation for the character string stored in chars. 
The code: 

chars = "delete foo; logout"; 

call abbrev_ (addr (chars), length (chars), code); 

calls the command processor with the string arrived at by expanding the command 
line: 

delete foo; logout 
That is, if foo is an abbreviation for *.pll, the command processor is given the line: 
del ete *.pl 1 ; logout 

to be executed. 

The code: 

chars = some_str i ng; 
cp = addr (chars) ; 
xcp = addr (xchars) ; 

call abbrev_$expanded_l i ne (cp, length (chars), 
xcp, length (xchars) , out_ptr, out_len) ; 

copies some_string into chars and leaves the expanded version in xchars, unless the 
length of the expanded version is greater than length(chars). In that case the expanded 
version is in allocated storage. In either case, out_ptr points to the expanded version 
and out_len is its length. 
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absolute_pathname_ 



Name: absolute pathname 

The absolute_pathname_ subroutine is used to convert a relative or absolute pathname 
into a full absolute pathname. This entry does not accept the syntax for specifying 
archive component pathnames; if one is supplied, an error code is returned. See the 
information on naming conventions in the Programmer's Reference Manual for details. 

USAGE 

del absol ute_pathname_ entry (char (*) , char (*) , fixed bin (35)); 
call absol ute_pathname_ (pathname, f ul l_pathname, code); 
ARGUMENTS 
pathname 

is the relative or absolute pathname to be expanded. (Input) 
full_pathname 

is the full, absolute pathname derived from the input pathname. (Output) 

code 

is a standard system error code. (Output) If an error has occurred, it can have 

one of the following values: 

error_table_$lesserr 

too many less-than ("<") characters in pathname. 
error_table_$badpath 

invalid syntax in pathname. 
error_table_$pathlong 

the expanded pathname is longer than 168 characters. 
error_table_$entlong 

the entryname portion of the expanded pathname is longer than 32 characters. 
error_table_$archive_pathname 

the input pathname specified an archive component; this feature is only 

supported by the expand_pathname_$component and 

expand_pathname_$component_add_suf f ix entrypoints. 
error_table_$no_wdir 

a relative pathname is specified, but no working directory is in force for the 

process. 
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absolute_pathname_ active_f nc_err_ 



Entry: absolute pathname $add suffix 

This entrypoint expands a relative or absolute pathname into a full, absolute pathname, 
adding a suffix to the entry name if that suffix is not already present 

USAGE 

del absol ute_pathname_$add_suf f ix entry (char (*) , char (*) , char (*) , 
fixed bin (35)) ; 

call absol ute_pathname_$add_suf f ix (pathname, suffix, f ull_pathname, 
code) ; 

ARGUMENTS 
pathname 

is the relative or absolute pathname to be expanded. (Input) 
suffix 

is the suffix to be added to the entryname portion of the pathname. (Input) The 
period separating the entryname and the suffix must not be included. If a null 
string is supplied, no suffix is added. 

full_pathname 

is the full, absolute pathname derived from the input pathname. (Output) 

code 

is a standard system error code. (Output) It can have the same values described 
for absolute_pathname_. 



Name: active fnc err 

The active_fnc_err_ subroutine is called by active functions when they detect unusual 
status conditions. This subroutine formats an error message and then signals the 
condition active_function_error. The default handler for this condition prints the error 
message and then returns the user to command level. See the Programmer's Reference 
Manual for additional information on default handling. 

Since this subroutine can be called with a varying number of arguments, it is not 
permissible to include a parameter attribute list in its declaration. 

USAGE 

declare act i ve_f nc_err_ entry options (variable); 

call act i ve_f nc_err_ (code, caller, control_str i ng , argl, argN) ; 
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ARGUMENTS 
code 

is a standard status code (fixed bin(35)). (Input) 
caller 

is the name (char(*)) of the calling procedure. It can be either varying or 
nonvarying. (Input) 

control_string 

is an ioa_ subroutine control string (char(*)). This argument is optional. See 
"Notes" below. (Input) 

argi 

are ioa_ subroutine arguments to be substituted into control_string. These 
arguments are optional. However, they can only be used if the control_string 
argument is given first. See "Notes" below. (Input) 

NOTES 

The error message prepared by the active_fnc_err_ subroutine has the format: 
caller: system_message userjnessage 

where: 
caller 

is the caller argument described above and should be the name of the procedure 
detecting the error. 

system_message 

is a standard message from a standard status table corresponding to the value of 
code. If code is equal to 0, no system_message is returned. 

user_message 

is constructed by the ioa_ subroutine from the control_string and argi arguments 

described above. If the control_string and argi arguments are not given, 
user_message is omitted. 
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add_bit_offset_ 



Entry: active fnc err $suppress name 

This entry point is functionally the same as active_fnc_err_, but it suppresses the 
caller name and the colon at the beginning of the error message. The caller name is 
nevertheless passed to the active_function_error handier. 

USAGE 

declare act i ve_f nc_err_$suppress_name entry options (variable); 

call act ive_f nc_err_$suppress_name (code, caller, control string, 
argl , argN) ; 

where all arguments are the same as above. 



Name: add bit offset 

This function returns a pointer to a bit relative to the bit referenced by the input 
pointer. The displacement to the desired bit may be positive, negative, or zero. 

USAGE 

declare add_b i t_of f set_ entry (ptr, fixed bin (24)) returns (ptr) 
reducible; 

new_poi nter_val ue = add_b i t_of f set_ (poi nter_val ue, bi t_di splacement) ; 

ARGUMENTS 

pointer_value 

is the original pointer to which the bit displacement is applied. (Input) 
bit_displacement 

is the displacement in bits to be applied to the above pointer. (Input) 

new_pointer_value 

is the result of this operation. (Output) 

NOTES 

If the result of applying the displacement would cause the pointer to reference outside 
the legal boundaries of a segment (either a negative offset or an offset beyond 256K 
words), the result of the call is not defined. 
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add_bit_offset_ 



add_char_offset_ 



EXAMPLES 

The program fragment 

current_bi t_ptr = add_b i t__of f set_ (cur rent_b i t_ptr , -1); 
changes the value of current_bit_ptr to locate the previous bit in the segment. 



Name: add__char_offset 

This function returns a pointer to a character relative to the character referenced by 
the input pointer. The displacement to the desired character may be positive, negative, 
or zero. 

USAGE 

declare add_char_of f set_ entry (ptr, fixed b:n (21)) returns (ptr) 
reducible; 

new_poi nter_value = add_char_of f set_ (poi nter_val ue, char_d i spl acement) ; 

ARGUMENTS 

pointer_value 

is the original pointer to which the character displacement is applied. (Input) 
char_displacement 

is the displacement in characters to be applied to the above pointer. (Input) 

new_pointer_ value 

is the result of this operation. (Output) 

NOTES 

If the pointer supplied to add_char_offset_ does not point to a character boundary, 
this operation is applied to a pointer value which references the character containing 
the bit located by the input pointer. 

Thus, the program fragment: 

a_ptr = add_char_of f set_ (a_ptr, 0); 

may be used to insure that "a_ptr" points to a character boundary. 

If the result of applying the displacement would cause the pointer to reference outside 
the legal boundaries of a segment (either a negative offset or an offset beyond 256K 
words), the result of the call is not defined. 



2-10 



AG93-05 



add_char_of f set_ add_epilogue_handler_ 

EXAMPLES 

The program fragment: 

current_char_ptr = add_char_of f set (current_char_ptr , -1) ; 

changes the value of current_char_ptr to locate the previous character in the segment 



Name: add epilogue handler 

The add_epilogue_handler_ subroutine is used to add an entry to the list of those 
handlers called when a process or run unit is terminated. A program established as an 
epilogue handler during a run unit is called when the run unit is terminated. If the 
process continues after the run unit is terminated, the handler is discarded from the 
list of those called when the process is terminated. Hence, epilogue handlers 
established during a run unit are not retained beyond the life of the run unit 

USAGE 

declare add_ept 1 ogue_hand 1 er_ entry (entry, fixed bin (35)); 

call add_epi logue_handler_ (ev, code); 

ARGUMENTS 

ev 

is an entry value to be placed on the list of such values to be called when the 
run unit or process is cleaned up. (Input) 

code 

is a standard status code. (Output) 
NOTE 

The add_epilogue_handler_ subroutine effectively manages two lists of epilogue 
handlers: those for the run unit, if a run unit is active, and those for the process. 
While a run unit is active, it is not possible to add entries to the list for the process. 
There is no way to establish a process epilogue handler while a run unit is active. 
The caller of execute_epilogue_ (logout, new_proc, etc.) must indicate whether all or 
just the run unit handlers are to be invoked. 
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Name: adjust bit count 

The adjust_bit_count_ subroutine performs the basic work of the adjust_bit_count 
command. It is called to find the last nonzero word or character of a segment or 
multisegment file and set the bit count accordingly. In the case of a multisegment 
file, empty trailing components are deleted and the returned bit count is the sum of 
the bit counts of the nonzero components. Only the bit count of the last component 
is altered. 

USAGE 

declare adj us t_b i t_count_ entry (char(l68) aligned, char (32) aligned, 
bit(l) aligned, fixed bin (35), fixed bin (35)); 

call adjust_bi t_count_ (dir_name, entryname, char_sw, bit_count, code); 

ARGUMENTS 

dir_name 

io uiv {muuuuuv vi uib vuii iciu.iixi£ unwiui ji. vhil/ul/ 

entryname 

is the entryname of the segment. (Input) 
char_sw 

is the character switch. (Input) 

"0"b adjusts to last bit of last nonzero word. 

"l"b adjusts to last bit of last nonzero character. 

bit_count 

is the computed bit count for the segment- (Output) If the value is less than 0, 
it indicates that no attempt to compute the count was made (code is nonzero). If 
the value is greater than or equal to 0, the computed value is correct, whether or 
not the bit count could be set. 

code 

is a standard status code. (Output) 
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Name: aim check 

The aim_check_ subroutine provides a number of entry points for determining the 
relationship between two access attributes. An access attribute can be either an 
authorization or an access class. See also the read_allowed_, read_write_allowed_, and 
write_allowed_ subroutines in this document 



Entry: aim check $equal 

This entry point compares two access attributes to determine whether they satisfy the 
equal relationship of the access isolation mechanism (AIM). 

USAGE 

declare aim_check_$equal entry (bit (72) aligned, bit (72) aligned) 
returns (bit(l) aligned); 

returned_bit = a im_check_$equal (acc_attl, acc_att2) ; 

ARGUMENTS 

acc_atti 

are access attributes. (Input) 

returned_bit 

is the result of the comparison. (Output) 

"l"b acc_attl equals acc_att2. 

"0"b acc_attl does not equal acc_att2. 



Entry: aim check Sgreater 

This entry point compares two access attributes to determine whether they satisfy the 
greater -than relationship of the AIM. 

USAGE 

declare a im_check_$greater entry (b i t (72) aligned, b i t (72) aligned) 
returns (bit(l) aligned); 

retur ned_b i t = a im_check_$ greater (acc__attl, acc__att2) ; 
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ARGUMENTS 

acc_atti 

are access attributes. (Input) 

returned_bit 

is the result of the comparison. (Output) 

'T'b acc_attl is greater than acc_att2. 

"0"b acc_attl is not greater than acc_att2. 



Entry: aim check Sgreater or equal 

This entry point compares two access attributes to determine whether they satisfy 
either the greater-than or the equal relationships of the AIM. 

USAGE 

declare aim_check_$greater_or_equal entry (bit (72) aligned, bit (72) 
aligned) returns (bit(l) aligned); 

returned_bit = a im_check_$greater_or_equal (acc_attl, acc_att2) ; 

ARGUMENTS 

acc_atti 

are access attributes. (Input) 

returned_bit 

is the result of the comparison. (Output) 

'T'b acc_attl is greater than or equal to acc_att2. 

"0"b acc_attl is not greater than or equal to acc_att2. 



| Entry: aim check Sin range 

| Returns a flag indicating whether a specified access attribute is within the specified 
| access attribute range. 

[ USAGE 

declare aim_check_$ i n_range entry (bit (72) aligned, (2) bit (72) aligned) 
returns (bit(l) aligned); 

| result = aim_check_$ i n_range (test_acc_att , acc_att_range) ; 

I ARGUMENTS 

i 

I test_acc_att 

is the access attribute to be tested to see if it is within the range. (Input) 
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acc_att_range 

is an access attribute range. (Input) 

in_range 

will be 'T'b if and only if acc_att_range (2) > 
(Output) 



Name: aim util. 

The aim_util_ subroutine contains entrypoints that manipulate AIM access classes and 
authorizations. 

Entry: aim util $get__access class 

This entry point extracts the access class from an authorization. 
USAGE 

declare aim_ut i l_$get_ac.cess_cl ass entry (bit (72) aligned) returns 
(bit (72) aligned); 

access_class = aim_uti l_$get_access_c 1 ass (authorization); 

ARGUMENTS 

authorization 

is a standard AIM authorization marking. (Input) 
access_class 

is a standard AIM access class marking. (Output) 
Entry: aim util $get privileges 

This entry point extracts the privileges from a standard AIM authorization. 
USAGE 

declare aim_uti l_$get_pr ivi leges entry (bit (72) aligned) returns 
(bit (36) aligned); 

privileges = aim_uti l_$get_pr ivi leges (authorization); 



i 

= test_acc_att >= acc_att_range (1). 
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ARGUMENTS 

authorization 

is a standard AIM authorization marking. (Input) 

privileges 

is a standard AIM privilege string. (Output) See the include file aim_privileges.incl.pll 
for the interpretation of this string. 

Entry: aim util $get__level 

This entry point extracts the sensitivity level from an access class or authorization. 
USAGE 

declare aim_uti l_$get_level entry (bit (72) aligned) returns (fixed bin); 

level = aim_uti l_$get_level (access_class) ; 

ARGUMENTS 

access_class 

is a standard AIM access class or authorization marking. (Input) 

level 

is a sensitivity level number. (Output) Levels range from 0 to 7. Level names are 
available via system_info_$level_names. 

Entry: aim util Sget categories 

This entry point extracts the categories from a standard AIM access class or 
authorization. 

USAGE 

declare a im_ut i l_$get_categor i es entry (bit (72) aligned) returns 
(bi t (36) al i gned) ; 

categories = aim_uti l_$get_categor ies (access_c 1 ass) ; 
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ARGUMENTS 
access_class 

is a standard AIM access class or authorization marking. (Input) 
categories 

is a bit string representing the category information contained in the access class. 
(Output) If the i'th bit of the bit string is a 1, then the i'th category is included 
in the access class marking. Category names are available from 
system_inf o_$category_names. 



Entry: aim util Smake access class 

This entry point constructs an access class marking from a level and a set of 
categories. 

USAGE 

declare aim_ut i l_$make_access_cl ass (fixed bin, bit (36) aligned, bit (72) 
al igned) ; 

call aim_ut i l_$make_access_c 1 ass (level, categories, access_c 1 ass) ; 

ARGUMENTS 

level 

is a sensitivity level number, from 0 to 7. (Input) 
categories 

is a category bit string. (Input) See aim_util_$get_categories for the construction 
of this string. 

access_class 

is a standard AIM access class marking. (Output) 



Name: archive 

The archive, subroutine is used to access individual components in archives, list the 
components of an archive, and obtain information about archive components. 
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Entry: archive $get component 

This entry, given a pointer to an archive and its bitcount, and the name of the 
desired component in the archive, returns a pointer to the component and the bitcount 
of the component. It is used when there is a specific component in the archive which 
is to be referenced. For applications that wish to serially access all the components in 
an archive, archive_$next_component is more appropriate. This entry only returns a 
pointer and length for the component; if more information is desired, the 
archive_$get_component_info entrypoint should be used. 

USAGE 

declare archi ve_$get_component entry (pointer, fixed bin (24), char (*) , 
pointer, fixed bin(24), fixed bin(35))» 

call arch i ve_$get_component (arch i ve_ptr , archive_bc, component_name, 
component_ptr , component_bc, code); 

ARGUMENTS 

archive_ptr 

is a pointer to the archive segment to be searched. (Input) It need not point to 
the base of a segment; it is converted to a segment base pointer by archive_, so 
a pointer to anywhere in the segment may be given here. 

archive_bc 

is the bitcount of the archive segment. (Input) 
component_name 

is the name of the component to be searched for- (Input) It can be up to 32 
characters long. 

component_ptr 

is a pointer to the first word of the archive component if the specified 
component was found, or null otherwise. (Output) It is a pointer into the segment 
pointed to by archive_ptr. 

component_bc 

is the bitcount of the archive component pointed to by component_ptr. (Output) 
It describes a region of the archive segment which contains the specified 
component; if an attempt is made to reference past the end of this area, invalid 
data may be referenced. 
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code 

is a standard system status code, one of the following: (Output) 

error_table_$no_component 

indicates that the specified component was not found in the archive. 

error_table_$not_archive 

indicates that archive_ptr points to a segment which does not appear to be a 
properly formatted archive. 

error_table_$archive_f mt_err 

indicates that, although the segment pointed to by archive_ptr does appear to 
be a valid archive, it contains an incorrectly formatted archive header. The 
archive should be repaired before further use either by extracting all the 
still-accessible components and creating a new archive, or by manipulating it 
with a text editor to access the apparent components. 



Entry: archive $get component info 

This entry, given a pointer to an archive and its bitcount, and the name of the 
desired component in the archive, fills in a caller-supplied structure with information 
describing the archive component. Also see archive_$get_component and 
archi ve_$next_component_inf o. 

USAGE 

declare arch i ve_$get_component_i nf o entry (pointer, fixed bin (24), 
char (*) , pointer, fixed bin (35)); 

call arch i ve_$get_component_i nf o (arch i ve_ptr , archive_bc, 
component_name, arch i ve_component_i nf o_ptr , code) ; 

ARGUMENTS 

archive_ptr 

is a pointer to the archive segment to be searched. (Input) It need not point to 
the base of a segment; it is converted to a segment base pointer by archive_, so 
a pointer to anywhere in the segment can be given here. 

archive_bc 

is the bitcount of the archive segment. (Input) 
component_name 

is the name of the component to be searched for. (Input) It can be up to 32 
characters long. 

archi ve_component_inf o_ptr 

is a pointer to a user-supplied archive_component_info structure, described below. 
(Input) The caller must have previously set archive_component_info. version to the 
appropriate version number, currently ARCHIVE_COMPONENT_INFO_VERSION_l. 
The structure is filled in with information describing the selected archive 
component if it can be found. 
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code 

is a standard system status code. (Output) It can have any of the values which 
can be returned by archive_$get_component, and can also have the following 
value: 

error_table_$unimplemented_version 

indicates that the version number in the caller-supplied archive_component_info 
structure is not correct. 



STRUCTURE 



The archive_component_info_ptr points to the following structure (described in the 
archive_component_info.incl.pll include file): 

del 1 arch i ve_component_i nf o aligned based (arch i ve_component_i nfo_ptr) , 

2 version fixed bin, 

2 comp_bc fixed bin (24), 

2 comp_ptr ptr, 
2 name char (32) unaligned, 

2 time modified fixed bin (70. 
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2 comp_lth fixed bin (19). 

2 access bit (36) unaligned; 



STRUCTURE ELEMENTS 



version 

must be set to ARCHIVE_COMPONENT_INFO_VERSION_l by the caller. All 
other structure elements are output 



comp_bc 

is the bit_count of the archive component 
comp_ptr 

is a pointer to the base of the component 



name 

is the name of the component 



time_modified 

is a clock reading corresponding to the date/ time contents modified of the 
segment from which this component was most recently updated. This is the value 
reported in the "modified" column by the "ac tl" command. It may be inaccurate 
by several hours if the archive was updated in a different time zone than the 
current time zone. 



time_updated 

is a clock reading corresponding to the date/ time when this component was last 
updated in the archive. This is the value reported in the "updated" column by 
the "ac tl" command. It may be inaccurate by several hours if the archive was 
updated in a different time zone than the current time zone. 
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comp_lth 

is the size, in words, of the component. Both the size in words and the 
bit_count are provided as a convenience to the caller. The size in words is 
derived from the bit_counL 

access 

is the representation of the effective access mode recorded with the archive 
component. The first bit is "r" access, the second is "e", and the third is "w". 
Even if "a" access appears in the archive itself, it will be ignored. 



Entry: archive Slist components 

This entry, given a pointer to an archive and its bitcount, and a pointer to an area, 
allocates an array of archive_component_info structures in the area to describe all the 
components in the archive, and returns a pointer to and the size of this array. This 
entry is intended to be used in applications where it is more convenient to loop 
through an array processing archive components than it is to step through the 
components by using archive_$next_component_info. There is no corresponding list 
interface which just returns name, pointer and bit_count; the complete 
archive_component_info structure is always supplied. 

USAGE 

declare arch i ve_$ 1 i st_components entry (pointer, fixed bin (24), fixed 
bin, pointer, pointer, fixed bin, fixed bin(35))» 

call arch i ve_$ i i st_components (arch i ve_ptr , archive_bc, i nfo_version, 
area_ptr, arch i ve_component_i nf o_array_ptr , n_components , code); 

ARGUMENTS 

archive_ptr 

is a pointer to the archive segment to be searched. (Input) It need not point to 
the base of a segment; it is converted to a segment base pointer by archive_, so 
a pointer to anywhere in the segment can be given here. 

archive_bc 

is the bitcount of the archive segment. (Input) 
info_version 

is the version number for the archive_component_info structure array which will 
be allocated and returned. (Input) The only supported version is 
ARCHIVE_COMPONENT_INFO_VERSION_l. 

area_ptr 

is a pointer to a caller-supplied area in which the returned array of 
archive_component_infos will be allocated. (Input) If area_ptr is null, no list will 
be allocated, but n_components will still be set; this can be used when it is 
desired to merely count the components in the archive. 
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archive_component_inf o_array_ptr 

is a pointer returned which points to an array of archive_component_info 
structures describing all the components in the archive. (Output) It should be 
declared as follows: 

del 1 arch i ve_component_i nfo_array (n_components) aligned 
like arch i ve_component_i nfo based 
(archi ve_component_i nf o_array_ptr) ; 

The version number in all the elements of this array will be the same as was 
passed in the info_version argument. The archi ve_component_info_array_ptr will 
be null if there are no components in the archive; n_components will be returned 
as zero, and the code will be zero as well. It will also be null if a null area_ptr 
was supplied. 

n_components 

is the number of components in the archive. (Output) This can be zero if the 
archive is empty, and is still valid. 

code 

is a standard system status code, one of the following: (Output) 

error_table_$not_archive 

indicates that archive_ptr points to a segment which does not appear 
to be a properly formatted archive. 

error_table_$archive_f mt_err 

indicates that, although the segment pointed to by archive_ptr does appear to 
be a valid archive, it contains an incorrectly formatted archive header. The 
archive should be repaired before further use either by extracting all the 
still-accessible components and creating a new archive, or by manipulating it 
with a text editor to access the apparent components. 



Entry: archive Snext component 

This entry, given a pointer to an archive and its bitcount, and a pointer to the base 
of a component (or null), returns a pointer to the next component in the archive, its 
name, and its bitcount If there are no components remaining in the archive, the 
pointer is returned null on output. The first time this is called for a particular 
archive, the component pointer should be supplied as null. This entry is intended to 
be used to step through all the components of an archive, one at a time. The archive 
should not be modified while this is being done, or the results will be unpredictable. 
See also archi ve_$get_component and archi ve_$next_component_info. 

USAGE 

declare arch i ve_$next_component entry (pointer, fixed bin(2l»), pointer, 
fixed bin(2l*)> char (*) , fixed bin(35)); 

call arch i ve_$next_component (arch i ve_ptr , archive_bc, component_ptr , 
component_bc, component_name, code) ; 
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ARGUMENTS 
archive_ptr 

is a pointer to the archive segment to be searched. (Input) It need not point to 
the base of a segment; it is converted to a segment base pointer by archive_, so 
a pointer to anywhere in the segment can be given here. 

archive_bc 

is the bitcount of the archive segment (Input) 
component_ptr 

on input, this is a pointer to the previous component in the archive, or null to 
indicate that the next component should be the first component in the archive. 
(Input/ Output) On output, this is a pointer to the next component in the archive, 
or null if there are no components remaining after the one it pointed to on 
input 

component_bc 

is the bitcount of the selected component (Output) 

component_name 

is the name of the selected component (Output) 

code 

is a standard system status code, one of the following: (Output) 

error_table_$not_archive 

indicates that archive_ptr points to a segment which does not appear 
to be a properly formatted archive. 

error_table_$archi ve_f mt_err 

indicates that, although the segment pointed to by archive_ptr does appear to 
be a valid archive, it contains an incorrectly formatted archive header. The 
archive should be repaired before further use either by extracting all the 
still-accessible components and creating a new archive, or by manipulating it 
with a text editor to access the apparent components. 



Entry: archive $next component info 

This entry, given a pointer to an archive, the bitcount of the archive, and a pointer 
to the base of a component (or null), returns a pointer to the next component in the 
archive and fills in an archive_component_info structure to describe it If there are 
no components remaining in the archive, the pointer is returned null on output. The 
first time this is called for a particular archive, the component pointer should be 
supplied as null. See also archive_$get_component_info and archive_$next_component. 
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USAGE 



declare arch i ve_$next_component_i nf o entry (pointer, fixed bin (2*0, 
pointer, pointer, fixed bin (35)); 

call arch i ve_$next_component_i nf o (archive_ptr , archive_bc, 
component_ptr , arch i ve_component_i nf o_ptr , code); 



ARGUMENTS 



archive_ptr 

is a pointer to the archive segment to be searched. (Input) It need not point to 
the base of a segment; it is converted to a segment base pointer by archive.., so 
a pointer to anywhere in the segment may be given here. 



archive_bc 

is the bitcount of the archive segment (Input) 



component_ptr 

on input, this is a pointer to the previous component in the archive, or null to 
indicate that the next component should be the first component in the archive. 
(Input/Output) On output, this is a pointer to the next component in the archive, 
or null if there are no components remaining after the one it pointed to on 
input 

archive_component_inf o_ptr 

is a pointer to a user-supplied archive_component_info structure, described in the 
description of the archive_$get_component_info entrypoint (Input) The caller must 
have previously set archive_component_info. version to the appropriate version 
number, currently ARCHI VE_COMPONENT_INFO_VERSION_l . The structure is 
filled in with information describing the selected archive component if component_ptr 
is returned non-null. 



code 

is a standard system status code. (Output) It may have any of the values which 
can be returned by archive_$next_component, and may also have the following 
value: 

error_table_$unimplemented_version 

indicates that the version number in the caller-supplied archive_component_info 
structure is not correct. 
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Name: area info 

The area_info_ subroutine returns information about an area. 
USAGE 

declare area_info_ entry (ptr, fixed bin (35)); 
call area_info_ (info_ptr, code); 
ARGUMENTS 
info_ptr 

points to the structure described in "Notes" below. (Input) 

code 

is a system status code. (Output) 
NOTES 

The structure pointed to by info_ptr is described by the following PL /I declaration 
(defined by the system include file, area_info.incl.pll): 



del 1 area_info 

2 version 

2 control , 
3 extend 
3 2ero_on_al loc 
3 2ero_on_free 
3 dont_free 
3 no_freeing 
3 system 
3 mbz 

2 owner 

2 n_components 
2 size 

2 vers i on_of_area 
2 areap 

2 al 1 oca ted_b locks 
2 free_blocks 
2 al 1 ocated_words 
2 free_words 

STRUCTURE ELEMENTS 



al i gned based, 
fixed bin, 

bi t (1) unal i gned, 
bi t (1) unal igned, 
bi t (1) unal igned, 
bi t (1) unal igned, 
bi t (1) unal igned, 
bi t (1) unal igned, 
bi t (30) una 1 i gned, 
char (32) unal i gned, 
fixed bin, 
fixed bin (30) , 
fixed bin, 
ptr, 

fixed bin, 
f i xed bin, 
fixed bin (30) , 
fixed bin (30) ; 



version 

is set by the caller and should be 1. 
control 

are control bits describing the format and type of the area. 
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extend 

indicates whether the area is extensible. 
"l"b yes 
"0"b no 

zero_on_alloc 

indicates whether blocks are cleared (set to all zeros) at allocation time. 
'T'b yes 
"0"b no 

zero_on_free 

indicates whether blocks are cleared (set to all zeros) at free time. 
'T'b yes 
"0"b no 

dont_free 

indicates whether free requests are disabled (for debugging). 
'T'b yes 
"0"b no 

no_freeing 

indicates whether the allocation method assumes no freeing will be done. 
'T'b yes 
"0"b no 

system 

causes the use of hcs_$make_seg instead of get_temp_segments to create the first 
component It assumes that the original area is all zeroes, rather than explicitly 

'T'b yes 
"0"b no 

mbz 

is not used and must be zeros, 
owner 

is the name of the program that created the area if the area is extensible. 

n_components 

is the number of components in the area. 

size 

is the total number of words in the area. 
version_of_area 

is 0 for (old) buddy system areas and 1 for standard areas, 
areap 

is filled in by the caller and can point to any component of the area. 



11/86 



2-29 



AG93-05A 



area info area info 



allocated_blocks 

is the number of allocated blocks in the area. 

free_blocks 

is the number of free blocks in the area (not including virgin storage within 
components, i.e., storage after the last allocated block). 

allocated_words 

is the number of allocated words in the area. 

free_words 

is the number of free words in the area not counting virgin storage. 

No information is returned about version 0 areas except the version number. 

If the no_freeing bit is on OT'b), the counts of free and allocated blocks are 
returned as 0. 



Entry: area inf o $get block data info 

This en try point returns a pointer and length for the first biock or next block in an 
area, and whether or not it is free. This allows a program to step through an area 
looking at each block in turn. Extensible areas are handled correctly. 

USAGE 

declare area_i nf o_$get_block_data_i nf o entry (ptr, bit (1), ptr, ptr, 
ptr, fixed bin (18) , bit (1), fixed bin (35)); 

call area_i nf o_$get_block_data_i nf o (area_ptr, next_ptr_f 1 ag , 

block_data_ptr , output_area_ptr , next_data_ptr , data_size, 
block_al located_f 1 ag, code); 

ARGUMENTS 

area_ptr 

is a pointer to the area in which the data block will be found. (Input) 
next_ptr_flag 

if "l"b, then return information about the block after the one pointed to by a 
block_data_ptr. (Input) 

block_data_ptr 

pointer to a data block in the area. If it is null then it will be internally 
initialized to the first block in the area. (Input) 
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output_area_ptr 

is a pointer to the area which actually contains the block about which information 
is returned, it will be equal to area_ptr unless the area is extensible and the 
returned block information required going to the next segment in the area. When 
stepping through the blocks in an area, this pointer should be used as input (i.e. 
area_ptr) for the next call. (Output) 

next_data_ptr 

is a pointer to the block in which information is returned. It will be equal to 
block_data_ptr unless next_ptr_flag was set, in which case it will point to the 
block after the one pointed to by block_data_ptr. (Output) 

data_size 

is the size, in words, of the returned data block. (Output) 
block_allocated_flag 

If "l"b, then the block is allocated. If "0"b, then the block is free. (Output) 

code 

is a standard system status code, it is returned as error_table_$end_of_info if the 
block about which information is requested is in virgin storage in the area (i.e. 
the end of the area has been reached). (Output) 



Name: arithmetic to ascii 

The arithmetic_to_ascii_ subroutine formats any arithmetic value into a compact ascii 
form. An integer, fractional, or exponential format can be used, depending on the 
number to be converted. Fixed-point numbers are truncated during the formatting 
process; floating-point numbers are rounded. 

USAGE 

declare ar i thmet i c_to_asc i i_ entry (ptr, fixed bin, bit(l) aligned, 
fixed bin, fixed bin, char (132) varying); 

call ar i thmet ic_to_asci i_ (v_ptr, type, packed, precision, scale, 
resul t) ; 
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ARGUMENTS 
v_ptr 

is a pointer to the value to be converted. (Input) It can be any arithmetic data 
type (real or complex, fixed or float, binary or decimal, single or double 
precision). 

type 

is a standard Multics descriptor type. (Input) See the Programmer's Reference 
Manual for a list of standard Multics data types. 

packed 

indicates whether the value is packed or unpacked. (Input) 
"0"b value is unpacked. 
"l"b value is packed. 

precision 

is the precision of the value to be converted. (Input) 

scale 

is the scale factor of the value to be converted. (Input) 
result 

is the character-string representation of the value to be converted; it contains no 
blanks. (Output) 

NOTES 

If the value is complex, the real and imaginary parts are formatted by correcting them 
to float decimal(59) and converting each part separately. The result returned by the 
arithmetic_to_asciL subroutine is the concatenation of the real and imaginary converted 

parts, with a leading sign and trailing "i" supplied for the imaginary part. 



Name: ascii__to_bcd 

The ascii_to_bcd subroutine performs isomorphic (one-to-one reversible) conversion 
from ASCII to BCD. 

USAGE 

del asci i_to_bcd_ entry (char (*) , bit(*)); 
call ascii to bed (ascii in, bed out); 
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ARGUMENTS 
ascii_in 

is the ascii input characters tro convert to BCD. (Input) 
bcd_out 

is the BCD equivalent of the input string. (Output) Note that both upper and 
lower case ASCII characters are converted to the single case BCD characters. 
ASCII characters that do not have a match in BCD will be converted to a 
question mark (?). For more information see "Notes" below. 

NOTES 

The ASCII question mark (?) and any ASCII characters (other than lowercase letters) | 
will be mapped into a BCD question mark (?). The valid BCD characters are as 
follows: 

0123456789 [@:?ABCDEFGHI&.] (<\ A JKLMNOPQR-$*);';/STUVWXYZ_,%= #<space> 

BCD must be aligned on a 6-bit BCD character boundary. i 



Name: ascii to ebcdic 

The ascii_to_ebcdic_ subroutine performs isomorphic (one-to-one reversible) conversion 
from ASCII to EBCDIC. The input data is a string of valid ASCII characters. A 
valid ASCII character is defined as a 9-bit byte with an octal value in the range 
0 <= octal_value <= 177. 

This entry point accepts an ASCII character string and generates an EBCDIC character 
string of equal length. 

USAGE 

declare asc i i_to_ebcdi c_ entry (char (*) , char (*) ) ; 
call asc i i_to_ebcd i c_ (ascii_in, ebcdic_out) ; 
ARGUMENTS 
ascii_in 

is a string of ASCII characters to be converted. (Input) 
ebcdic_out 

is the EBCDIC equivalent of the input string. (Output) 
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Entry: ascii to ebcdic_$ae table 

This entry point defines the 128-character translation table used to perform conversion 
from ASCII to EBCDIC. The mappings implemented by the ascii_to_ebcdic_ and 
ebcdic_to_ascii_ subroutines are isomorphic; i.e., every valid character has a unique 
mapping, and mappings are reversible. (See the ebcdic_to_ascii_ subroutine.) The result 
of an attempt to convert a character that is not in the ASCII character set is 
undefined. 

USAGE 

declare asc i i_to_ebcd i c_$ae table char (128) external static; 
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ISOMORPHIC ASCII/EBCDIC CONVERSION TABLE 
ASCII EBCDIC 
GRAPHIC OCTAL HEXADECIMAL GRAPHIC 



NUL 


000 


00 


NUL 


SOH 


001 


01 


SOH 


STX 


002 


02 


STX 


ETX 


003 


03 


ETX 


EOT 


004 


37 


EOT 


ENQ 


005 


2D 


ENQ 


ACK 


006 


2E 


ACK 


BEL 


007 


2F 


BEL 


BS 


010 


16 


BS 


HT 


01 1 


05 


HT 


LF 


012 


25 


NL 


VT 


013 


OB 


VT 


FF 


014 


OC 


NP 


CR 


015 


OD 


CR 


SO 


016 


OE 


SO 


SI 


017 


OF 


S 1 


DLE 


020 


10 


DLE 


DC1 


021 


1 1 


DC1 


DC2 


022 


12 


DC2 


DC3 


023 


13 


TM 


DC4 


024 


3C 


DC4 


NAK 


025 


3D 


NAK 


SYN 


026 


32 


SYN 


ETB 


027 


26 


ETB 


CAN 


030 


18 


CAN 


EM 


031 


19 


EM 


SUB 


032 


3F 


SUB 


ESC 


033 


27 


ESC 


FS 


034 


1C 


IFS 


GS 


035 


ID 


IGS 


RS 


036 


IE 


IRS 


US 


037 


IF 


IUS 


space 


040 


40 


space 


! 


041 


5A 


1 


m 


042 


7F 


11 


# 


043 


7B 


# 


$ 


044 


5B 


$ 


% 


045 


6C 


% 




046 


50 


& 


i 


047 


7D 




( 


050 


4D 


( 


) 


051 


5D 


) 




052 


5C 


* 


+ 


053 


4E 


+ 
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ASCII EBCDIC 
GRAPHIC OCTAL HEXADECIMAL GRAPHIC 



9 




Ar 


* 






6o 




• 


0^6 






/ 


0£7 
up/ 


6i 

O 1 


/ 
/ 


w 


oAn 

wow 


FO 
r w 


w 


1 

1 


OAl 


F 1 
r i 


1 




0A2 


F2 




•3 
J 


nA^ 


P ^ 
' J 




L 

H 


oAli 

WO*T 


Fli 
r h 


J. 


C 
J 


oA5 


F5 


C 


A 

o 


oAA 

wow 


FA 
r o 


A 

o 


7 


nA7 

wo / 


F7 


7 

1 


8 

w 


w / w 


f8 

r o 


fi 
u 


Q 


07 1 

W/ 1 


FQ 


Q 


• 


mo 


7 A 

t ' * 




; 
i 


07^ 


? l 




< 


W / H 




< 




n7£ 


7F 




> 


07A 
w / o 


6F 

W L_ 


> 


? 


077 


6F 

o r 


? 


IS) 


inn 

1 WW 


7f 


(a) 


A 


101 

1 W 1 


C 1 

W 1 


A 


R 


1 0? 

1 Wfc 




R 


c 


101 


CI 


c 


D 


104 


Clf 


D 


F 


i wp 




E 


F 

r 


106 


C6 


F 


G 


107 


C7 


G 


H 


1 10 


C8 


H 


I 


1 1 1 


C9 


I 


J 


1 12 


Dl 


J 


K 


113 


D2 


K 


L 


111* 


D3 


L 


M 


115 


Dh 




N 


116 


D5 


N 


0 


117 


D6 


0 


P 


120 


07 


P 


Q 


121 


D8 


Q 


R 


122 


D9 


R 


S 


123 


E2 


S 


T 


12*4 


E3 


T 


U 


125 


El* 


U 


V 


12b 


t5 


V 


w 


127 


E6 


w 


X 


130 


E7 


X 
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ASCII 
GRAPHIC OCTAL 



EBCDIC 
HEXADECIMAL GRAPHIC 



Y 


131 


E8 


Y 


Z 


132 


E9 


Z 


[ 


133 


AD 


[ (see "Notes") 


\ 


13* 


E0 


\ 


] 


135 


BD 


] (see "Notes") 




136 


5F 


logical NOT 





137 


6D 





accent 


140 


79 


g r a v e accent 


a 


141 


81 


a 


b 


142 


82 


b 


c 


143 


83 


c 


d 


144 


84 


d 


e 


145 


85 


e 


f 


146 


86 


f 


g 


147 


87 


g 


h 


150 


88 


h 


i 


151 


89 


i 


j 


152 


91 


j 


k 


153 


92 


k 


1 


154 


93 


1 


m 


155 


94 


m 


n 


156 


95 


n 


o 


157 


96 


0 


P 


160 


97 


P 


q 


161 


98 


q 


r 


162 


99 


r 


s 


163 


A2 


s 


t 


164 


A3 


t 


u 


165 


A4 


u 


V 


166 


A5 


V 


w 


167 


A6 


w 


X 


170 


A7 


X 


y 


171 


A8 


y 


2 


172 


A9 


z 


{ 


173 


CO 


{ 




174 


4F 


sol i d bar 




175 


DO 


} 


ti Ide 


176 


Al 


ti Ide 


DEL 


177 


07 


DEL 
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NOTES 

The graphics ([ and ]) do not appear in (or map into any graphics that appear in) 
the standard EBCDIC character set. They have been assigned to otherwise "illegal" 
EBCDIC code values in conformance with the bit patterns used by the TN text 
printing train. 

Calling the ascii_to_ebcdic_ subroutine is as efficient as using the PL /I translate 
builtin. since conversion is performed by a single MVT instruction and the procedure 
runs in the stack frame of its caller. 

This mapping differs from the ASCII to EBCDIC punched card code mapping as 
discussed in the Programmer's Reference Manual. The characters that differ when 
mapped are: C ] \ and NL (newline). 
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Name: ask 

The ask_ subroutine provides a flexible terminal input facility for whole lines, strings 
delimited by blanks, or fixed -point and floating-point numbers. Special attention is 
given to prompting the terminal user. 

The main entry point returns the next string of characters delimited by blanks or tabs 
from the line typed by the user. If the line buffer is empty, the ask_ subroutine 
formats and types out a prompting message and reads a line from the user_input I/O 
switch. 

USAGE 

declare ask_ entry options (variable); 
call ask_ (ctl, ans, ioa_args); 
ARGUMENTS 
ctl 

is an ioa_ control string (char(*)) in the same format as that used by the ioa_ 
subroutine. (Input) 

ans 

is the return value (char(*)). (Output) 
ioa_args 

are any number of arguments to be converted according to ctl. (Input) 
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Entry: ask $ask__c 

This entry point tests to determine if there is anything left on the line. If so, it 

returns the next symbol, as in the ask_$ask_ entry point, and sets a flag to 1. 

Otherwise, it sets the flag to 0 and returns. 

USAGE 

declare ask_$ask_c entry (char (*) , fixed bin); 

call ask_$ask_c (ans, flag); 

ARGUMENTS 

ans 

is the next symbol, if any. (Output) 

flag 

is the symbol flag. (Output). Its value can be: 
1 if the symbol is returned. 
0 if there is no symbol. 



Entry: ask $ask cint 

This entry point is a conditional entry for integers. If an integer is available on the 
line, it is returned and the flag is set to 1. If the line is empty, the flag is set to 0. 
If there is a symbol on the line, but it is not a number, it is left on the line and 
the flag is set to -1. 

USAGE 

declare ask_$ask_c i nt entry (fixed bin, fixed bin); 

call ask_$ask_ci nt (int, flag); 

ARGUMENTS 

int 

is the returned value, if any. (Output) 

flag 

is the int flag. (Output). Its value can be: 
1 if int is returned. 
0 if the line is empty. 
-1 if there is no number. 
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Entry: ask $ask cfio 

This entry point works like the ask_$ask_cint entry point but returns a floating value, 
if an integer is available. 

USAGE 

declare ask_$ask_cf lo entry (float bin, fixed bin); 

call ask_$ask_cf lo (flo, flag); 

ARGUMENTS 

flo 

the returned value, if any. (Output) 

flag 

is the flow flag. (Output). Its value can be: 

0 if the line is empty. 

1 if the value is returned. 
-1 if it is not a number. 



Entry: ask $ask cline 

This entry point returns any part of the line that remains. A flag is set if the rest 
of the line is empty. 

USAGE 

declare ask_$ask_c 1 i ne entry (char (*) , fixed bin); 

call ask_$ask_cl ine (line, flag); 

ARGUMENTS 

line 

is the returned line, if any. (Output) 

flag 

is the line flag. (Output). Its value can be: 
1 if the line is returned. 
0 if the line is empty. 
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Entry: ask $ask clr 

This entry point clears the internal line buffer, Because the buffer is internal static, 
the input of one program can accidentally be passed to another unless the second 
begins with a call to this entry point. If a value typed by the user is incorrect and 
if the program wishes to ask for the line to be retyped, the ask_$ask_clr entry point 
can also be called. 

USAGE 

declare ask_$ask__c 1 r entry; 
cal 1 ask_$ask_cl r ; 



Entry: ask $ask cnf 

This entry point works like the ask_$ask_cint entry point except that it returns a 
value of "on" or "off" if an integer is available. 

USAGE 

declare ask_$ask_cnf entry (char (*) , fixed bin); 

call ask_$ask_cnf (ans, flag); 

ARGUMENTS 

ans 

is a value of "on" or "off" if such a value is present. (Output) 

flag 

is the yn flag. (Output). Its value can be: 
1 if a "on" or "off" value is returned. 
0 if the line is empty. 
-1 if the next value on the line is not "on" or "off" 



Entry: ask Sask cyn 

This entry point works like the ask_$ask_cint entry point except that it returns a 
value of yes (or y) or no (or n) if an integer is available. 
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USAGE 

declare ask_$ask_cyn (char (*) , fixed bin); 



ans 

call ask_$ask_cyn (ans, flag); 
ARGUMENTS 
ans 

is a value of yes (or y) or no (or n) if such a value is present. (Output) 

flag 

is the yn flag. (Output). Its value can be: 

1 if a yes (or y) or no (or n) value is returned. 
0 if the line is empty. 
-1 if the next value on the line is not yes (or y) or no (or n). 



Entry: ask $ask int 

This entry point works the same as the ask_$ask_ entry point except that the next 
item on the line must be a number. An integer value is returned. Numbers can be 
fixed point or floating point, positive or negative. A leading dollar sign or a comma 
is ignored. If the value typed is not a number, the program types: 

"string" nonnumeric. Please retype: 

and waits for the user to retype the line. 

USAGE 

declare ask_$ask_int entry options (variable); 
call ask_$ask_int (ctl, int, ioa_args); 
ARGUMENTS 
ctl 

is an ioa_ control string (char(*)) in the same format as that used by the ioa_ 
subroutine. (Input). If a period is typed, zero is returned. 

int 

is the return value (fixed bin). (Output) 
ioa_args 

are any number of arguments to be converted according to ctl. (Input) 
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Entry: ask Sask flo 

This entry point works like the ask_$ask_int entry point except that it returns a 
floating value. 

USAGE 

declare ask_$ask_f lo entry options (variable); 
call ask_$ask_flo (ctl , flo, ioa_args) ; 
ARGUMENTS 
ctl 

is an ioa_ control string (char(*» in the same format as that used by the ioa_ 
subroutine. (Input). If a period is typed, zero is returned. 

flo 

is the return value (float bin). (Output) 
ioa_args 

are any number of arguments to be converted according to ctl. (Input) 



Entry: ask_$ask line 

This entry returns the remainder of the line typed by the user. Leading blanks are 
removed. If there is nothing left on the line, the program prompts and reads a new 
line. 

USAGE 

declare ask_$ask_l i ne entry options (variable); 
call ask_$ask_l i ne (ctl, line, ioa_args) ; 
ARGUMENTS 
ctl 

is an ioa_ control string (char(*)) in the same format as that used by the ioa_ 
subroutine. (Input). If a period is typed, zero is returned. 

line 

is the return value (char(*)). (Output) 
ioa_args 

ar*» anv numhpr r*f ai-oiimpntc try Vv» r.f\nvt*Tt(>A nr.rr\rr\\rta tn r.tl fTnmitl 

"»'""" ~- *"D— — . — — — -D — * J ' 
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Entry: ask Sask n 

This entry point scans the line and returns the next symbol without changing the line 
pointer. A call to the ask_ entry point later returns the same value. 

USAGE 

declare ask_$ask__n entry (char (*) , fixed bin); 

call ask_$ask_n (ans, flag); 

ARGUMENTS 

ans 

is the returned symbol, if any. (Output) 

flag 

is the ans flag. (Output). Its value can be: 

0 if the line is empty. 

1 if the symbol is returned. 



Entry; ask Sask nf 

This entry point works like ask_$ask_yn except that it returns a value of "on" or 
"off". 

USAGE 

declare ask_$ask_nf entry options (variable); 
call ask_$ask_nf (ctl, line, ioa_args) ; 
ARGUMENTS 
ctl 

is an ioa_ control string (char(*)) in the same format as that used by the ioa_ 
subroutine. (Input) If a period is typed, zero is returned. 

line 

is the return value (char(*)). (Output) 
ioa_args 

are any number of arguments to be converted according to ctl. (Input) 
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This entry point scans the line for floating point numbers. 
USAGE 

declare ask_$ask_nf lo entry (float bin, fixed bin); 

call ask_$ask__nf lo (flo, flag); 

ARGUMENTS 

flo 

is the returned value, if any. (Output) 

flag 

is the flow flag. (Output). Its value can be: 

0 if the line is empty. 

1 if the value is returned. 

— 1 if it If ~+ « 

x li it id uui a iiumuvi. 



Entry: ask Sask nint 

This entry point scans the line for integers. The second argument is returned as -1 if 
there is a symbol on the line but it is not a number, 1 if successful, and 0 if the 
line is empty. 

USAGE 

declare ask_$ask_n i nt entry (fixed bin, fixed bin); 

call ask_$ask_ni nt (int, flag); 

ARGUMENTS 

int 

is the returned value, if any. (Output) 

flag 

is the int flag. (Output). Its value can be: 
1 if int is returned. 
0 if the line is empty. 
-1 if there is no number. 
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Entry: ask Sask nline 

This entry point initiates a scan of the rest of the line. 
USAGE 

declare ask_$ask_nl i ne entry (char (*) , fixed bin); 

call ask_$ask_nl i ne (line, flag); 

ARGUMENTS 

line 

is the returned line, if any. (Output) 

flag 

is the line flag. (Output). Its value can be: 
1 if the line is returned. 
0 if the line is empty. 



Entry: ask $ask_nnf | 

This entry point returns the next symbol, if it is an "on" or "off" value, without | 
changing the line pointer. j 

USAGE j 

declare ask_$ask_nnf entry (char (*) , fixed bin); | 

call ask_$ask_nnf (ans, flag); j 

ARGUMENTS | 

ans 

is a value of "on" or "off" if such a value is present. (Output) 

flag 

is the yn flag. (Output). Its value can be: 
1 if a "on" or "off" value is returned. 
0 if the line is empty. 
-I if the next value on the line is not "on" or "off." 
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Entry: ask $ask_nyn 

This entry point returns the next symbol, if it is a yes (or y) or no (n) value, 
without changing the line pointer. The arguments are the same as those used with the 
ask_$ask_cint entry point. 

USAGE 

declare ask_$ask_nyn entry (char (*) , fixed bin); 

call ask_$ask_nyn (ans, flag); 

ARGUMENTS 

ans 

is a value of yes (or y) or no (or n) if such a value is present (Output) 

flag 

is the yn flag. (Output). Its value can be: 

1 if o *7/»e ( r\r tr\ /v» *i r\ ( r\-r r>\ iroliia ic ratiirno/1 

JL 11 U J VJ VU1 J/ Ul XXV/ VV/1 XX/ TU1UV XL> X VbUI UVUi 

0 if the line is empty. 

-1 if the next value on the line is not yes (or y) or no (or n) 
Entry: ask Sask prompt 

This entry point deletes the current contents of the internal line buffer and prompts 
for a new line. The line is read in and the entry returns. 

USAGE 

declare ask_$ask_prompt entry options (variable); 
call ask_$ask_prompt (ctl, ioa_args) ; 
ARGUMENTS 
ctl 

is a control siring (char(*)) similar to that typed by the ioa_ subroutine. (Input) 
ioa_args 

are any number of arguments to be converted according to ctl. (Input) 
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Entry: ask_$ask_setline 

This entry point sets the internal static buffer for the ask_ subroutine to the given 
input line so that the line can be scanned. 

USAGE 

declare ask_$ask_setl i ne entry (char (>'<)); 
call ask_$ask_setl i ne (line); 
ARGUMENTS 
line 

is the line to be placed in the ask_ buffer. (Input). Trailing blanks are removed 
from line. A carriage return is optional at the end of line. 



Entry: ask Sask yn 

This entry point works like the ask_$ask_int entry point except that it returns a value | 

of yes (or y) or no (or n). Its arguments are the same as those used with the | 
ask_$ask_int entry point 

USAGE 

declare ask_$ask_yn entry options (variable); 
call ask_$ask_yn (ctl, ans, ioa_args) ; 
ARGUMENTS 
ctl 

is an ioa_ control string (char(*)) in the same format as that used by the ioa_ 
subroutine. (Input). If a period is typed, zero is returned. 

ans 

is a value of yes (or y) or no (or n) if such a value was present (Input) | 
ioa_args 

are any number of arguments to be converted according to ctl. (Input) 
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Name: assign 

The assign_ subroutine assigns a specified source value to a specified target. This 
subroutine handles the following data types: 1-12, 19-22, 33, 34, 41-46. Any other 
type will produce an error. This subroutine uses rounding in the conversion when the 
target is floating point or when the source is floating and the target is character, and 
uses truncation in all other cases. 

USAGE 

declare assign_ entry (ptr, fixed bin, fixed bin(35)> ptr, fixed bin, 
fixed bin(35)) ; 

call assign_ (target_ptr , target_type, target_l ength , source_ptr, 
source_type, source_l ength) ; 

ARGUMENTS 

target_ptr 

points to the target of the assignment; it can contain a bit offset. (Input) 
target_type 

specifies the type of the target; its value is 2*M+P where M is the Multics 
standard data type code (see the Programmer's Reference Manual) and P is 0 if 

the target is unpacked and 1 if the target is packed. (Input) 

target_length 

is the string length or arithmetic scale and precision of the target. If the target 
is arithmetic, the target_length word consists of two adjacent unaligned half words. 
The left half word is a fixed bin(17) representing the signed scale and the right 
half word is a fixed bin(18) unsigned integer representing the precision. (Input) 
The include file encoded_precision.incl.pll declares this as: 

del 1 encoded_prec i s i on based aligned, 

2 scale fixed bin (17) unaligned, 

2 prec fixed bin(l8) unsigned unaligned; 



source_ptr 

points at the source of the assignment; it can contain a bit offset. (Input) 
source_type 

specifies the source type using the same format as target_type. (Input) 
source_length 

is the string length or arithmetic scale and precision of the source using the same 
format as targetjength. (Input) 
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Entry: assign Scomputational 

The assign_$computational_ entry assigns a specified source value to a specified target 
It can handle any computational Multics data type. This includes all PL/I 
computational data and all COBOL and FORTRAN data types. This entry uses the 
same rules for rounding and truncation as assign_. 



USAGE 



declare ass i gn_$computat ional_ entry (ptr, ptr, fixed bin (35)); 
call assign_$computational_ (tar_str_ptr , src_str__ptr , code); 
ARGUMENTS 



tar_str_ptr 

is a pointer to a structure which defines the address and attributes of the target. 
The format of this structure is defined below. (Input) 



src_str_ptr 

is a pointer to a structure giving the attributes of the source. This structure has 
the same format as the one used for the target. (Input) 



is a standard system code. It will be zero if the conversion was sucessful, or 
error_table_$bad_conversion if either data type was not computational. It is also 
possible that the conversion condition will be signalled, if the source data can not 
be converted to the requested target type. (Output) 



NOTES 



The format of the structures used to 
computational_data.incl.pll. It is: 

del 1 computat i onal_data 
2 address 
2 data_type 
2 flags 

3 packed 

3 pad 
2 prec__or_l ength 
2 scale 

2 pi cture_image_ptr 



describe the source and target data is given by 



a 1 i gned based, 
ptr al i gned, 
f i xed b i n (1 7) » 
al igned, 
bit(l) unal, 
bit (35) unal, 
f ixed bin {2k) , 
fixed bin(35) » 
ptr al i gned; 



STRUCTURE ELEMENTS 



address 

is a pointer to the data where the data is (source) or where it is to go (target). 
It is the responsibility of the caller to ensure that there is sufficient room for 
the target. 
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dala_type 

is a standard Multics data type. A list of all Multics data types appears in the 

Programmer's Reference Manual. The include file std_descriptor_types.incl.pll 
defines symbolic names for these types. 

packed 

is "l"b if the data is packed. 

pad 

is reserved for expansion and must be all "0"b. 
prec_or_length 

is the arithmetic precision or string length of the data, as appropriate. 

scale 

is the arithmetic scale factor of the data, or zero if the data is not arithmetic. 
picture_image_ptr 

for picture data, is a pointer to the picture image block for the picture, otherwise 
it is ignored. A picture image block is a structure in the runtime symbol table. 
Only PL/ 1 and the Multics debuggers know how to access it, so user programs 
should not try to convert to or from pictures using this entry. 



Entry: assign__$assign_round__ 

This entry assigns a source value to a target value, but always rounds. Otherwise it is 
identical to assign_. 



Entry: assign_3assign__truncate_ 

This entry is identical to assign, except that it always truncates. 



Name: bed to ascii 

The bcd_to_ascii_ subroutine performs isomorphic (one-to-one reversible) conversion 
from BCD to ASCII. 

USAGE 

del bcd_to_asc i i_ entry (b 1 1 (*) , char(*)); 
call bed to ascii (bed in, ascii out); 
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ARGUMENTS 
bcd_in 

is a bit string that represents the BCD characters to convert. (Input) 
ascii_out 

is the lower case ASCII equivalent of the input string. (Output) 
NOTES 

BCD must be aligned on a 6-bit BCD character boundary. 



Name: before journal manager 

The before_journal_manager_ subroutine provides the means to manipulate, and obtain 
information about, before journals. Before journals are used to store before images of 
protected data management (DM) files, for the purpose of rolling back modifications 
to these files in the event of failure. 

See the section entitled "Multics Data Management" in the Programmer's Reference 
Manual, Order No. AG91, for a complete description of before journals and their 
use. 



Entry: bef ore journal manager $close b j 

This entry point closes the specified before journal, making it unavailable to the 
current process. A journal can be opened more than once in a process, in which case 
the same opening id is returned for each open request. In that case, the close 
operation merely decreases by one the number of journal openings in the process. If 
a close_bj request is issued by a process on a journal while the process still has an 
active transaction in that journal, the journal cannot be closed and an error code is 
returned to the caller. If the journal to be closed was the default before journal for 
the process, the before journal which was last opened in the process (if any) becomes 
the default before journal (see "Notes" under the set_default_bj entry). 

USAGE 

declare before_journal_manager $close_bj entry (bit (36) aligned, fixed 
bin (35)); 

call before_journal_manager_$close_bj (bj_openi ng_id, code); 

ARGUMENTS 

bj_opening_id 

is the opening identifier of the before journal. (Input) 
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code 

is a standard system error code. (Output) 



Entry: bef ore journal manager Screate b j 

This entry point creates a before journal file as specified by the input arguments. 
USAGE 

declare before_Journal_manager_$create_bj entry (char (>'<) , char (*) , fixed 
bin, fixed bin, fixed bin(35))» 

call bef ore_journal_manager_$create_bj (dir_name, entry_name, 
n_control_i nterval s, control_interval_size, code); 

ARGUMENTS 

dir_name 

is the pathname of the directory in which the before journal is to be created. 
(Input) 

entry_name 

is the entry name of the before journal to be created. The .bj suffix must be 
included. (Input) 

n_control_intervals 

is the size of the journal expressed in the number of control intervals. (Input) A 
before journal is a circular file; when information is no longer useful (i.e., before 
images for committed or aborted transactions), it will be overwritten, allowing the 
space to be reused. In estimating the size of a journal, you should consider the 
number of transactions to be using the journal simultaneously, as well as their 
profiles, i.e., their length in time and the rate at which they modify data, to 
optimize performance. 

control_interval_size 

is the size of the before journal control interval in number of bytes. (Input) The 
size is currently fixed at 4096. 
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code 

is a standard system error code. (Output) 



Entry: before journal manager $get bj path from oid 

This entry point returns the directory pathname and the entry name of the specified 
before journal. For this operation to be successful, the before journal must be open 
in the current process. 

If a zero code is returned, the operation is successful and the dir_name and 
entry_name arguments are set to the proper values. If a nonzero code is returned, the 
operation did not succeed and the values of dir_name and entry_name are left 
unchanged. 

USAGE 

declare before_journal_manager_$get_bj_path_f rom_oid entry (bit (36) 
aligned, char (*) , char (*) , fixed bin (35)); 

call bef ore__journal_manager_$get_bj_path (bj_oid, dir_name, entry_name, 
code) ; 

ARGUMENTS 

bj_oid 

is the opening identifier of the before journal for which the pathname is 
requested. (Input) 

dir_name 

is the pathname of the directory in which the before journal resides. (Output) 
entry_name 

is the entry name of the before journal. (Output) 

code 

is a standard system error code. (Output) 



Entry: bef ore journal manager $get def ault b j 

This entry point returns the opening identifier of the before journal to be used as the 
default in those cases where a before journal specification is expected but not 
supplied. The rules for determining this default before journal are described in 
"Notes" under the set_default_bj entry point. If the journal which is to serve as the 
default before journal is not open at the time of this call, it is opened automatically. 
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USAGE 

declare bef ore_journal_manager_$get_def aul t_bj entry (b i t (36) aligned, 
fixed bin (35)) ; 

call before_journal_manager_$get_def aul t_bj (bj_oid, code); 

ARGUMENTS 

bj_oid 

is the opening identifier of the current default before journal. (Output) 

code 

is a standard system error code. (Output) 



Entry: before journal manager $open bj 

This entry point makes the before journal specified by the pathname, ready for use by 
any transaction of the current process. A process may have several before journals 
open at the same time, and may also have the same journal opened more than one 
time. When a transaction is started, one of the open journals must be associated with 
the transaction, if the transaction needs a before journal. One can expect that in most 
cases, a process will open only one before journal, which will be used by all its 
transactions. 

This entry may also change the default before journal for the process to the newly 
opened journal (see "Notes" under set_default_bj). 

USAGE 

declare bef ore_journa 1 _manager_$open_bj entry (char (*) , char (*) , bit (36) 
aligned, fixed bin (35)); 

call bef ore_journal_manager_$open_bj (dir_name, entry_name, 
bj_openi ng_id, code); 

ARGUMENTS 

dir_name 

is the pathname of the directory in which the before journal to be opened 
resides. (Input) 

entry_name 

is the entry name of the before journal to be opened. The .bj suffix must be 
included (Input) 

bj_opening_id 

is the opening identifier of the journal. (Output) This specifier must be used 
subsequently by the current process to identify this journal. 
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code 

is a standard system error code. (Output) 
NOTES 

When a before journal is opened, it is remembered in a per system table containing 
the pathnames and unique identifiers of all before journals opened in the system. This 
table is used after a system crash to determine which journals must be reopened and 
examined in order to perform a rollback operation. To preserve the integrity of this 
table, it is written out to disk automatically each time it is updated with a newly 
opened journal. 

If a process opens the same before journal more than one time, the opening identifier 
received from the open_bj will be the same for each call. The process must close a 
before journal the same number of times it opens it, to render the journal inaccessible 
through the same opening identifier. 



Entry: before journal manager $set default bj 

This entry point causes the specified before journal to become the default before 
journal. When no before journal is explicitly specified by the user at the beginning of 
a transaction, the default before journal for the process will be assigned to the 
transaction. The default before journal must be one of the before journals open in 
the process. 

USAGE 

declare bef ore_journal_manager_$set_def aul t_bj entry (bit (36) aligned, 
fixed bin(35)) ; 

call bef ore_journal_manager_$set_def aul t_bj (bj_openi ng_id, code); 

ARGUMENTS 

bj_opening_id 

is the opening identifier of the before journal. (Input) 

code 

is a standard system error code. (Output) 
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NOTES 

Several before_journal_manager_ entries expect an opening id to specify which before 
journal to use. If bj_opening_id is null, the following default assignments are 
attempted, in the order in which they are mentioned below, until one of them 
succeeds: 

• The current default before journal in this process, if there is one; otherwise, 

• The most recently open before journal among those that are still open, if there 
is one; otherwise, 

• The system before journal. If the system before journal has not been opened 
yet in the current process, it is automatically opened. 



Entry: bef ore journal manager $set transaction storage limit 

This entry point sets the maximum number of bytes a single transaction may use. 
USAGE 

declare bef or e_j our nal_manager_$set_tr ansae tion_s tor age_l imi t entry 
(char (*) , char (*) , fixed bin (35), fixed bin (35)); 

cal 1 bef ore_journa l_manager_$set_transact ion_storage_l imit (dir_name, 
entryname, storage_l imi t , code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the before journal. (Input) 
storage_limit 

is the maximum number of bytes a single transaction may use in the before 
journal. (Input) 

code 

is a storage system status code. (Output) 
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Name: bit offset 

The bit_offset_ subroutine returns the bit offset (relative to the base of the segment) 
of the bit located by the supplied pointer value. 

USAGE 

declare bit_offset_ entry (ptr) returns (fixed bin (2*0) reducible; 

bit_offset = bit_offset_ (poi nter_val ue) ; 

ARGUMENTS 

pointer_value 

is a pointer whose bit offset is to be determined. (Input) 
bit_offset 

is the bit offset of the supplied pointer. (Output) 
NOTES 

The first bit in a segment has a bit offset of zero. 



Name: cb menu 

The cb_menu_ subroutine allows a COBOL program to use the Multics menu facility 
(menu _). Through cb_menu_ a COBOL program may create a menu object, display the 
menu, and get a user-entered selection from a menu. Once a menu object has been 
created, the COBOL program can use this menu object by referencing it via a 
menu-id returned to the caller when the menu object was created or when a stored 
menu object was retrieved. 

The functionality available is provided through the various entry points described 
below. 



Entry: cb menu Screate 

Utilized to create a menu-object Returns a menu-id which may be subsequently used 
by other entry points. 
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USAGE 

declarations: 

01 choices-table. 



02 choices 


PIC X(nl) 


OCCURS 


(ml) 


TIMES. 


headers-tabl e. 










02 headers 


PIC X(n2) 


OCCURS 


(m2) 


TIMES. 


tra i 1 ers-tabl e 










02 trai lers 


PIC X(n3) 


OCCURS 


(m3) 


TIMES. 


keys-table. 










02 keys 


PIC X(l) 


OCCURS 


(mil) 


TIMES. 



01 menu-format. 

02 menu_version USAGE IS COMP-6 
02 constraints USAGE IS COMP-6 

03 max-width. 

03 max-height. 
02 no-of -columns USAGE IS COMP-6. 
02 flags. 

03 center-headers PIC 9(1). 

03 center-trailers PIC 9(1). 
02 pad-char PIC X (1) . 

01 menu-needs USAGE IS COMP-6. 
02 1 i nes-needed. 
02 width-needed. 
02 no-of-opt ions. 

77 menu- id USAGE IS COMP-6. 
77 ret-code USAGE IS COMP-6. 



call "cb_menu_$create" USING choices-table, headers-table, 
trailers-table, menu-format, keys-table, menu-needs, 
menu- id, ret-code. 

STRUCTURE ELEMENTS 



choices-table 

is a table of elementary data items which are the text of the options that the 
user wishes to display in the menu, nl is the length, in characters, of the longest 
character string comprising the text of an option, ml is the extent of the table, 
i.e., the number of options in the menu being described. This table must be at 
least of extent 1. 
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headers-table 

is a table of elementary data items to be displayed at the top of the menu. 
(Input) n2 is the length, in characters, of the longest header specified. m2 is the 
extent of the table, i.e., the number of headers (lines) desired. At least one 
header must be specified (if the first header is set to space(s), no headers will be 
used). 



trailers-table 

is an table of trailers (displayed immediately below the menu), 
are analogous to n2, m2 respectively. 



(Input) n3, m3, 



menu-format 

is a group item defining the format of the menu being created. (Input) 

In the COBOL program the caller is responsible for setting the following 
elementary data items: 



menu-vers i on 

max-width 

max-hei ght 

no-of -col umns 

center-headers 
center-trai lers 



the version number of the menu facility, 
(only version 1 is currently defined) 
maximum width of the window on which the 
menu is to be displayed, 
maximum height of window on which the 
menu is to be displayed, 
number of columns to be used to display 
the options. 

0 or 1 ; 0 = no, 1 = yes . 

0 or 1 (same as center-headers) 



keys-table 

is a table (maximum value of m4 is 61) that identifies the keystroke to be 
associated with each choice. (Input) This table must be at least as long as the 
number of choices in the menu. Each element in the table must be unique. 

menu-needs 

a group item that contains menu related information on successful execution of 
call. (Output) 

Returned information: 

lines-needed the number of lines required 

to display the menu, 
width-needed the number of columns needed 

to display the menu, 
no-of -opt ions the number of options defined 

in the menu. 
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menu-id 

the menu-object identifier (i.e., it is the menu object "pointer".) (Output) It must 
not be altered in any way by the application program. 

ret-code 

return code. (Output) (See Appendix B.) 



Entry: cb menu $delete 

Deletes a menu object from a given value segment. 
USAGE 

declarations: 

PIC X (168) . 
PIC X (32) . 
PIC X(32) . 

iicacc ic miAO-£ 



call "cb_menu_$del ete" USING dir-name, entry-name, name-of-menu, 
ret-code. 

STRUCTURE ELEMENTS 



dir-name 

pathname of the directory containing the menu object, (Input) 
entry-name 

entry name of value segment containing the menu object (Input) The suffix 
"value" need not be specified. 

name-of-menu 

name used to identify the menu object when the menu object was stored. (Input) 
ret-code 

return code. (Output) (See Appendix B.) 



77 dir-name 
77 entry-name 
77 name-of-menu 
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Entry: cb menu Sdescribe 

Returns information about a menu object It returns the number of options in the 
menu, the number of lines and number of columns required to display the menu. It 
is primarily used to determine if the menu can be displayed in a given window. 

USAGE 

declarations: 

01 menu-needs USAGE IS C0MP-6. 
02 1 ines-needed. 
02 width-needed. 
02 no-of -opt ions. 

77 menu- id USAGE IS C0MP-6. 
77 ret-code USAGE IS C0MP-6. 

call "cb_menu_$descr ibe" USING menu-id, menu-needs, ret-code. 
STRUCTURE ELEMENTS 



the menu identifier returned by cb_menu_$create (or cb_menu_$retrieve in cases 
where the menu object has been stored). (Input) 



a group item that contains menu related information on successful execution of 
call. (Output) 

Returned information: 



menu-id 



menu-needs 



1 i nes-needed 



the number of lines needed to 
display the menu. 



wi dth-needed 



the number of columns needed 
to display the menu. 



no-of -opt ion 



the number of options defined 
in the menu. 



ret-code 



return code. (Output) (See Appendix B.) 
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Entry: cb__menu__$destroy 

Used to free storage of a menu (not to be confused with cb_menu_$delete, which is 

used to delete the menu object from a value segment). Destroying the menu has no 
effect on the screen contents. 

USAGE 

declarations: 

77 menu- id USAGE IS COMP-6. 
77 ret-code USAGE IS COMP-6. 

call "cb_menu_$destroy" USING menu-id, ret-code. 



STRUCTURE ELEMENTS 



menu— id 

menu identifier returned by cb_menu_$create or cb_menu_$retrieve. (Input/Output) 
(If usage-mode is 0 (see cb_menu_$init2) this operand will be ignored.) Set to an 
invalid value on return to prevent the old menu-id from being accidentally used. 

ret-code 

return code. (Output) (See Appendix B.) 



Entry: cb menu Sdisplay 

Invoiced to display a menu in a given window. 
USAGE 

declarations: 

77 window- id USAGE IS COMP-6. 
77 menu- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_menu_$di splay" USING window-id, menu-id, ret-code. 



STRUCTURE ELEMENTS 



window-id 

a window identifier returned by cb_window_$create entry point. (Input) If 
usage-mode = 0 this operand will be ignored (see cb_menu_$init2). 
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menu-id 

menu identifier returned when the menu object was created or retrieved. (Input) 
ret-code 

return code. (Output) (See Appendix B.) 



Entry: cb menu $get__choice 

Returns the choice made by the user, i.e., a number representing either the menu item 
chosen or the function key (or its equivalent escape sequence) entered. 

USAGE 

declarations: 



77 


f unction-key- i nfo 


PIC X(nl) 






77 


wi ndow- id 


USAGE IS 


COMP- 


-6. 


77 


menu- id 


USAGE IS 


COMP 


-6. 


77 


f keys 


USAGE IS 


COMP 


-6. 


77 


sel ect i on 


USAGE IS 


COMP 


-6. 


77 


ret-code 


USAGE IS 


COMP- 


-6. 



call "cb_menu_$get_choi ce" USING window-id, menu-id, 
function-key-info, fkeys, selection, ret-code. 

STRUCTURE ELEMENTS 



window-id 

a window identifier returned by the cb_window_$create entry point. (Input) If 
usage-mode = 0 this operand will be ignored (see cb_menu_$init2). 

menu-id 

menu identifier returned by cb_menu_$create or cb_menu_$retrive. (Input) 
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function-key-info 

a character elementary data item (nl as required) used to specify the role of 
function keys (if they exist for the terminal being used) or an equivalent set of 
escape sequences if the terminal does not have function keys or not the function 
keys required by the application. (Input) The objective is to let the application 
use the terminal's function keys if possible, else specify key sequences to be used 
to simulate function keys. Each character in the string corresponds to one 
function key. If the character is a space, then it is not relevant if the 
corresponding function key exists or not. If the character is not a space, that 
character will be used to simulate a function key if the terminal does not have 
function keys. If the terminal does not have a function key for every non-space 
| character in the string, then function keys will be simulated. Thus, the string " 
| ?p q" means that the caller does not care whether the terminal has function key 
0 or 3, but the caller does wish to use function keys 1,2, and 4. If any of these 
3 function keys is not present on the terminal, then esc-? will substitute for Fl, 
esc-p will substitute for F2, and esc-q will substitute for F4. 

fkeys 

fkeys = 1 user entered a function key or escape sequence fkeys = 0 user selected 
an option (Output) 

selection 

is a number representing the choice made by the user. (Output) If the user has 
chosen an option, it is a number between 1 and the highest defined option. If 
the user has entered a function key, or escape sequence simulating a function key, 
it is the number associated with the function key. 

ret-code 

return code. (Output) (See Appendix B.) 

| Entries: cb menu__$initl, cb menu $init2 

These must be the first calls made to the menu manager. They set up the necessary 
environment for the menu application and return information concerning the user I/O 
window. 

USAGE 

dec 1 arat i ons : 

inter code 
integer usage-mode 

| call cb_menu_$ i ni t 1 

j call cb_menu_$ i ni t2 (usage-mode, user-wi ndow- 1 i nes, 

i user-window-columns, user-wi ndow- i d. ret-code) 
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STRUCTURE ELEMENTS 



usage-mode 

usage-mode = 0 means that the caller does not wish to do any explicit window 
management. (Input) When he/she wishes to display a menu, the window required 
will be automatically created. This means that the application will operate in a 
two window mode, the window containing the menu, and the user_io window. 
Both windows will be managed automatically for the user. If the user specifies 
this mode, all calls to the cb_window_ subroutine will be ignored and will return 
an appropriate error code. See Error Code Handling, below. All calls to the 
cb_menu_ subroutine that require a window identifier will ignore the user 
provided window-id. 

usage-mode = 1 means that the user wishes to define the number and 
characteristics of the windows to be used in the application. Thus, calls to 
cb_window_ will be supported and, for the entry points of cb_menu_ that require 
a window identifier, the caller must use a legal window-id (returned by 
cb_window_$create). 

user-window-lines 

the number of physical lines (rows) of the user i/o window when cb_menu_$init 

is called (which must be the first cb_menu_ call in the application.) Undefined if 
usage-mode = 0. (Output) 

user-window-columns 

the number of columns of the user i/o window at time that cb_menu_$init is 
called (see immediately above). (Output) Undefined if usage-mode = 0. 

user-window-id 

window identifier of the user i/o window. (Output) Undefined if usage-mode = 
0. 

ret-code 

return code. (Output) (See Appendix B.) 



Entry: cb menu $list 

Used to list the menu object(s), stored in value segment. The menu objects selected 
are those that match the string input by the caller. 
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USAGE 



decl arat ions: 



01 



matched-names . 
02 no-of-matches 
02 menu-names 



USAGE IS C0MP-6. 

PIC X(32) OCCURS (ml) TIMES. 



77 
77 
77 
77 



d i r-name 
entry-name 
match-str i ng 
ret-code 



PIC X (168) . 
PIC X(32) . 
PIC X(32) . 



USAGE IS COMP-6. 



call "cb_menu_$ 1 i st" USING di r-name, entry-name, match-string, 
matched-names, ret-code. 

STRUCTURE ELEMENTS 



dir-name 

pathname of directory containing the menu object (Input) 
entry-name 

entry name of value segment containing the menu object (Input) The suffix 
"value" need not be specified. 

match-string 

a character elementary data item that is to be used as the selection criteria for 
determining what menu object, if any, is contained in the specified value segment 
that match (or contain) this string. (Input) 

no-of-matches 

the number of matches found. (Output) If none, then it is 0. 
menu-names 

On return, contains the names of all menu objects, in the specified value segment, 
that match the character string match-string. (Output) Note, if ml is not large 
enough to contain all the names, only ml names will be returned. 

ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb_menu__$retrieve 

Used to retrieve a menu object previously stored via the cb_menu_$store subroutine. 
USAGE 

declarations: 



call "cb_menu_$retr i eve" USING dir-name, entry-name, name-of-menu, 
menu- id, ret-code. 

STRUCTURE ELEMENTS 



dir-name 

pathname of the directory containing the menu object (Input) 
entry-name 

entry name of value segment containing menu object. (Input) The suffix "value" 
need not be specified. 

name-of-menu 

name of the menu object used when the object was stored. (Input) 
menu-id 

is the menu id returned by the call. (Output) 
ret-code 

return code. (Output) (See Appendix B.) 



Entry: cb menu $store 

Used to store a menu object in a specified value segment 



77 dir-name 
77 entry-name 
77 name-of-menu 



PIC X (168) . 
PIC X(32) . 
PIC X(32) . 



77 menu- id 
77 ret-code 



USAGE IS COMP-6. 
USAGE IS COHP-6. 
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USAGE 

declarations: 

77 dir-name PIC X (1 68) . 

77 entry-name PIC X (32) . 

77 name-of-menu PIC X (32) . 

77 create-seg USAGE IS COMP-6. 

77 menu- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 



call "cb_menu_$ store" USING dir-name, entry-name, name-of-menu, 
create-seg, menu-id, ret-code. 

STRUCTURE ELEMENTS 



dir-name 

pathname of directory into which the menu object is to be placed. (Input) 
entry-name 

entry name of value segment into which menu object is to be placed. (Input) The 
suffix "value" need not be specified. 

name-of-menu 

is the name to be assigned to the stored menu object (Input) 
create-seg 

create-seg = 0 means do not store if value segment identified by entry-name does 
not already exist. (Input) create-seg = 1 means create value segment, if it does 
not already exist, and store menu object in it. 

menu-id 

is the menu object identifier returned by cb_menu_$create or cb_menu_$retrieve. 
(Input) 

ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb menu Sterminate 

Must be the last call to the menu manager in the menu application. 
USAGE 

declarations: none 

call "cb_menu_$ terminate". 

STRUCTURE ELEMENTS 
There are no arguments. 



Name: cb window 

This is the basic video interface subroutine to be used by COBOL to create /destroy /change 
windows. (If usage-mode = 0 (see cb_menu_$init2) this subroutine should not be 
called.) 

Its facilities are available through the following entry points. 



Entry: cb window Schange 

This entry points provides a facility for changing the size of an existing window. The 
size of a window can always be "shrunk", however it can be increased only it does 
not overlap with another defined window. (If usage-mode = 0 (see cb_menu_$init2) 
this entry point should not be called.) 

USAGE 

declarations: 

77 window- id USAGE IS COMP-6. 
77 first-line USAGE IS COMP-6. 
77 height USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6, 

call "cb_wi ndow_$change" USING window-id, first-line, height, 
ret-code. 
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STRUCTURE ELEMENTS 



window-id 

window identifier returned by cb_window_$create. (Input) 
first-line 

new first line number for the window being changed. (Input) A positive value, 
height 

new height for the window being changed. (Input) A positive value, 
ret-code 

return code. (Output) (See Appendix B.) 



Entry: cb window Sclear window 

Used to clear a specified window. 
USAGE 

declarations: 

77 window- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_window_$clear_window" USING window- id, ret-code. 



STRUCTURE ELEMENTS 



window-id 

the window identifier (returned by cb_window_$create) of the window to be 
cleared. (Input) 

ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb window ^create 

This entry is used to create a new window on the terminal screen. (If usage-mode = 
0 (see cb_menu_$init2) this entry point should not be called.) 



USAGE 



declarations: 



77 
77 
77 
77 
77 



swi tch-name 
f i rst-1 i ne 
hei ght 
wi ndow- i d 
ret-code 



PIC X(32) . 
USAGE IS COMP-6 
USAGE IS COMP-6 
USAGE IS COMP-6 
USAGE IS COMP-6 



call "cb_wi ndow_$ create" USING first-line, height, switch-name, 
window- id, ret-code. 



STRUCTURE ELEMENTS 



first-line 

is the line number where the window is to start (Input) 
height 

the number of lines used by the window, i.e., its height. (Input) 
switch-name 

the name that the caller wishes to associate with the switch. (Input) 
window-id 

the returned id of the window just created. (Output) It must not be altered in 
any way by the application program. 

ret-code 

return code. (Output) (See Appendix B.) 



Entry: cb_window $destroy 

Used to destroy a previously created window. (If usage-mode = 0 (see cb_menu_$init2) 
this entry point should not be called.) 
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USAGE 

dec 1 arat ions: 

77 window-id USAGE IS COMP-6. 
77 ret-code USAGE IS COMP-6. 

call "cb_wi ndow_$destroy" USING window- id, ret-code. 



STRUCTURE ELEMENTS 



window-id 

window identifier (returned by the cb_window_$create). (Input/Output) It is reset 
to an illegal value by this call. 

ret-code 

return code. (Output) (See Appendix B.) 
COBOL MENU APPLICATION EXAMPLES 

In the following two COBOL examples, a "Message" menu application is created that 
allows you to display, print, discard, or forward messages. Example 1 is a simple 
COBOL program that interfaces with the Multics menu manager via the cb_menu_ 
routine. Note in example 1 that window management functions are called automatically 
through arguments in the ft_menu_$init2 subroutine. 

Example 2 is a COBOL program that interfaces with the Multics menu manager 

through the cb_menu_routine; in example 2, however, window management functions 
are performed by the cb_window_ routine. 

EXAMPLE 1: 

In this example, all window management is done automatically. 

* A simple COBOL program interfacing with the Multics * 

* menu manager via the cb_menu_ routine. * 

it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it it >V it it it it it it it it it it it it it it it it it it it * it * * * ?V ft 

CONTROL DIVISION. 

DEFAULT GENERATE AGGREGATE DESCRIPTORS. 
IDENTIFICATION DIVISION. 

PROGRAM- I D . 

cbtestl . 

AUTHOR. 

R. I . 
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ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. 
Mul t i cs . 

OBJECT-COMPUTER. 
Mul t i cs . 

/***************^ 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 choices-table. 

02 choices PIC X (15) OCCURS 6 TIMES. 
01 headers-table. 

02 headers PIC X(H) OCCURS 1 TIMES. 
01 trai lers-table. 
02 trailers PIC X (32) OCCURS 1 TIMES. 

01 keys-table. 
02 keys PIC X(l) OCCURS 6 TIMES. 

01 menu-format. 

02 menu-version USAGE IS COMP-6 VALUE 1. 

02 constraints USAGE IS COMP-6. 

03 max-width VALUE 79- 

03 max-height VALUE 10. 

02 no-of-columns USAGE IS COMP-6 VALUE 2. 
02 flags. 

03 center-headers PIC 9(D VALUE 1. 

03 center-trailer PIC 90) VALUE 1. 
02 padder PIC X(l) VALUE 

01 menu-needs USAGE IS COMP-6. 
02 1 i nes-needed . 
02 width-needed. 
02 no-of -opt ions. 

77 dir-name PIC X (168) . 

77 entry-name PIC X (32) . 

77 menu-name PIC X (32) . 

77 function-key-info PIC X(l) VALUE "q". 

77 me PIC X (7) VALUE "cbtestl". 

77 menu- id 

USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

77 window- id USAGE IS COMP-6. 
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7 


f keys 


USAGE 


1 S 


COMP- 


-6. 


7 


opt i on 


USAGE 


1 5 


COMP* 


L 

O . 


7 


easy-mode 


USAGE 


IS 


COMP- 


-6 


7 


user-wi ndow-1 i nes 


USAGE 


IS 


COMP- 


-6. 


7 


user-wi ndow-columns 


USAGE 


IS 


COMP 


-6. 


7 


user-wi ndow- id 


USAGE 


IS 


COMP 


-6. 


7 


create-seg 


USAGE 


IS 


COMP 


-6. 


7 


keys-not-unique 


USAGE 


IS 


COMP 


-6. 


7 


too-few-keys 


USAGE 


IS 


COMP 


-6. 


7 


bad-arg 


USAGE 


IS 


COMP 


-6. 



PROCEDURE DIVISION. 

* The call to the cv_error_$name are used to collect the code for 

* certain error messages that are of interest this application. 

* Once these codes are retrieved the occurrence of that error can 

* be easily tested for. 



START- i T. 

CALL "cb_menu_$ini tl". 
CALL *'cb_menu_$ini t2" USING easy-mode, user-wi ndow-1 i nes, 
user-window-columns, user-wi ndow- i d, ret-code. 

* The calls to cb_menu_$ i n i t 1 & 2 MUST be the first calls to cb_menu_. 

* They set up the appropriate environment for the menu application. 

IF ret-code EQUAL TO zero GO TO NEXT-ERR-CODE . 
CALL "com_err_" USING ret-code, me, "Internal error. 

Could not set up appropriate environment.". 
GO TO STOP- IT. 

CALL "cv_error_$name" USING "menu_et_$keys_not_uni que" , 

keys-not-unique, ret-code. 
call "ioa_" USING "Error code for keys-not-unique = ~d", keys-not-unique. 
IF ret-code EQUAL TO zero GO TO NEXT-ERR-CODE. 

CALL "com_err_" USING ret-code, me, " (calling cv_er ror_$name) " . 
GO TO STOP- IT. 

NEXT-ERR-CODE. 

CALL "cv_error_$name" USING "error_table_$bad_arg", bad-arg, ret-code. 
IF ret-code EQUAL TO zero GO TO LAST-ERR-CODE . 

CALL "com_err_" USING ret-code, me , " (calling cv_er ror_$name) " . 
GO TO STOP- IT. 

LAST-ERR-CODE. 

CALL "cv_error_$name" USING "menu_et_$too_f ew_keys" , too-few-keys, 
ret-code. 

I F ret-code EQUAL TO zero GO TO SET-UP. 

CALL "com_err_" USING ret-code, me, " (calling cv_error_$name) " . 
GO TO STOP- IT. 
SET-UP. 
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MOVE 1 TO menu-version. 
MOVE "Display Message" TO choices(l). 
MOVE "Print Message" TO choices (2). 
MOVE "Discard Message" TO choices (3). 

MOVE "Forward Message" TO choices (*») . 
MOVE "Reply Message" TO choices (5). 

MOVE "List Messages" TO choices (6). 
MOVE " MULTICS MAIL " TO headers(l). 

MOVE "Press Fl or enter esc-q to quit" TO trailers(l). 
MOVE "1" TO keys (1) . 

MOVE "2" TO keys (2) . 
MOVE "3" TO keys (3) . 

MOVE "V TO keys (k) . 
MOVE "5" TO keys (5) . 
MOVE "6" TO keys (6) . 



MENU-CREATE. 

DISPLAY choices-table. 
DISPLAY menu-version. 

CALL "cb_menu_$create" USING choices-table, headers-table, 

trailers-table, menu-format, keys-table, menu-needs, 
menu- id, ret-code. 

* This call creates a menu object and return the menu object 

* identifier. This menu object is referenced as "menu- id", 
i r ret-coae l^iumu iu zero uu iu jiuKc-ntnu. 

CALL "com_err_" USING ret-code, me, " (calling cb_menu_$create) " . 
GO TO STOP- IT. 

STORE-MENU. 
MOVE ">udd>m>ri" TO dir-name. 
MOVE "menus_seg" TO entry-name. 
MOVE "cb__read_ma i l_menu" TO menu-name. 

MOVE 1 TO create-seg. 
CALL "cb_menu_$store" USING dir-name, entry-name, menu-name, 

create-seg, menu- id, ret-code. 
IF ret-code EQUAL TO zero GO TO DISPLAY-MENU. 

CALL "com_err_" USING ret-code, me, "(calling cb_menu_$ store) " . 
GO TO STOP- IT. 

DISPLAY-MENU. 

CALL "cb_menu_$di splay" USING window- id. menu- id. ret-code, 

* This call displays the menu in its own window at top of screen. 

* Since the usage-mode was set to 0, the program does not have to 

* create the window before calling cb_menu_$d i spl ay . 

* The window- id argument is ignored. 

IF ret-code EQUAL TO zero GO TO GET-CHOICE. 

CALL "com_err " USING ret-code, me, "Internal error. 
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Menu could not be displayed." 
GO TO STOP- IT. 
GET-CHOICE. 

* Defines the function key requirements, i.e., 

* if the terminal has function key 1 (Fl) then Fl will be used 

* to "quit", otherwise "esc q" will be used to "quit". 

CALL "cbjnenu_$get_choice" USING window- id, menu- id, 

function-key-info, fkeys, option, ret-code. 
IF ret-code EQUAL TO zero GO TO TEST-FKEY. 

CALL "com_err_" USING ret-code, me, "Internal error. While getting 

user's choice.". 
GO TO STOP- IT. 

TEST-FKEY. 
IF fkeys EQUAL TO 1 

CALL "ioa_" USING "Exiting at your request." 
GO TO STOP- IT 
ELSE 

CALL "?oa = " USING "You chose option ~d.", option 
GO TO GET-CHOICE. 

STOP-IT. 
CALL "cb_menu_$termi nate" . 

* cb_menu_$ term i nate MUST be the last call to cb_menu_ in the 

* application. It terminates the environment set up cb_menu_$ i n i t . 

EXIT PROGRAM. 



EXAMPLE 2: 

In this example, COBOL interfaces with the Multics menu manager and the Multics 
window manager via the cb_menu_ and cb_window_ subroutines, f i f 

/***************************************************************** 

* A simple COBOL program interfacing with the Multics * 

* menu manager and window manager via the cb_menu_ and * 

* cb_window_ routines, respectively. * 

****** * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
CONTROL DIVISION. 

DEFAULT GENERATE AGGREGATE DESCRIPTORS. 
IDENTIFICATION DIVISION. 

PROGRAM- ID. 
cbtest2. 

AUTHOR. 

R. ! . 



2-76 



AG93-05 



cb_window_ cb_window. 



ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. 
Mul tics. 

OBJECT-COMPUTER. 
Mul tics. 

DATA DIVISION. 
WORKING-STORAGE SECTION. 

01 choices-tablel . 

02 choicesl PIC X (9) OCCURS 2 TIMES. 
01 choices-table2. 

02 choices2 PIC X (15) OCCURS 6 TIMES. 
01 choi ces-tabl e3 . 

02 choices3 PIC X (21) OCCURS h TIMES. 
01 headers-table. 

02 headers PIC X(23) OCCURS 1 TIMES. 
01 trailers-table. 02 trailers PIC X (52) OCCURS 1 TIMES. 
01 keys-table. 02 keys PIC X(l) OCCURS 6 TIMES. 

01 menu-format. 02 menu-version USAGE IS COMP-6 VALUE 1. 02 
constraints USAGE IS COMP-6. 
03 max-width VALUE 80. 

03 max-height VALUE 10. 02 no^of columns USAGE IS COMP-6 VALUE 2. 
02 flags. 

03 center-headers PIC 9(1) VALUE 1. 
03 center-trailer PIC 9(1) VALUE 1. 
02 padder PIC X(l) VALUE 

01 menu-needs 1 USAGE IS COMP-6. 02 1 i nes-needed 1 . 02 
width-neededl . 02 no-of -opt ions 1 . 

01 menu-needs2 USAGE IS COMP-6. 02 1 i nes-needed2 . 02 
width-needed2. 02 no-of -opt i ons2 . 

01 menu-needs3 USAGE IS COMP-6. 02 1 i nes-needed3. 
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02 width-needed3. 
02 no-of-opt ions3. 

77 dir-name PIC X(l68) . 
77 entry-name PIC X (32) . 
77 menu-name PIC X (32) . 

77 function-key- info PIC X (2) VALUE "qf " . 
77 me PIC X (7) VALUE "cbtest2 ,, . 
77 switch-name PIC X (32) . 



lines-needed USAGE IS COMP-6. 
first-line USAGE IS COMP-6. 

height USAGE IS COMP-6. 

menu- id USAGE IS COMP-6. 

menu-idl USAGE IS COMP-6. 

menu-id2 USAGE IS COMP-6. 

menu-id3 USAGE IS COMP-6. 

ret-code USAGE IS COMP-6, 

curr-wi ndow- id USAGE IS COMP-6 * 

window- id USAGE IS COMP-6. 

window-idl USAGE IS COMP-6. 

window-id2 USAGE IS COMP-6. 

fkeys USAGE IS COMP-6. 

option USAGE IS COMP-6. 

do-it-yourself USAGE IS COMP-6 VALUE 1. 

user-wi ndow-1 i nes USAGE IS COMP-6. 

user-window-columns USAGE IS COMP-6. 

user -window- id USAGE IS COMP-6. 

create-seg USAGE IS COMP-6. 

bad-window- id USAGE IS COMP-6. 
nonexistent-window USAGE IS COMP-6. 
insuf f-room-for-wi ndow USAGE IS COMP-6. 



PROCEDURE DIVISION. 



* The call to the cv_error_$name are used to collect the code for 

* certain error messages that are of interest this application. 

* Once these codes are retrieved the occurrence of that error can 

* be easily tested for. 



START- IT. 

CALL "cv_error_$name" USING "video_et_$bad_wi ndow_id", 

- bad -wi ndow- id » ret-code* 
iF ret-code EQUAL TO zero GO TO NEXT-ERR-CODE . 

CALL "com_err_" USING ret-code, me, " (calling cv_error_$name) " . 
GO TO STOP- IT. 
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NEXT-ERR-CODE. 

CALL "cv_error_$name" USING "vi deo_et_$nonex i stent_wi ndow" , 

- nonexistent-window, ret-code. 

IF ret-code EQUAL TO 2ero GO TO LAST-ERR-CODE . 

CALL ,, com_err_" USING ret-code, me , " (calling cv_error_$name) " . 
GO TO STOP-ITT 

LAST-ERR-CODE. 

CALL "cv_error_$name" USING "video_et_$ i nsuf f_room_for_window", 

- i nsuf f -room-f or-wi ndow, ret-code. 
IF ret-code EQUAL TO zero GO TO SET-UP. 

CALL "com_err_" USING ret-code, me, " (calling cv_error_$name) " . 
GO TO STOP- IT. 
SET-UP. 

MOVE "Read Mail" TO choicesl (1) . 
MOVE "Send Mail" TO choicesl (2). 

MOVE "Display Message" TO choices2(l). 

MOVE "Print Message" TO choices2(2). 
MOVE "Discard Message" TO choices2(3). 
MOVE "Forward Message" TO choi ces2 (4) . 

MOVE "Reply Message" TO choices2(5). 

MOVE "List Messages" TO choices2(6). 

MOVE "Send New Message" TO choices3(l). 
MOVE "Send Deferred Message" TO choices3(2). 

MOVE "Print Sent Message" TO choices3(3). 

MOVE "Save Sent Message" TO choices3 W . 



MOVE "1" TO keys(l) . 

MOVE "2" TO keys (2) . 
MOVE "3" TO keys (3) . 

MOVE " V TO keys {k) . 
MOVE "5" TO keys (5) . 
MOVE "6" TO keys (6) . 



CALL "cb_menu_$ini tl". 

CALL "cb_menu_$ini t2" USING do-it-yourself, user -wi ndow- 1 i nes, 
- user-window-columns, user-wi ndow- i d, ret-code. 

* The call to cb_menu_$ i ni tl S 2 MUST be the first call to cb_menu_. 

* It sets up the appropriate environment for the menu application. 

* The application must do the window management, since 

* "do-i t-yousel f " is set to 1. 

IF ret-code EQUAL TO zero GO TO CREATE-F I RST-MENU. 
CALL "com_err_" USING ret-code, me, "Internal error. Could not set up 

appropriate environment.". 
GO TO STOP- IT. 
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CREATE-F I RST-MENU. 

* Create first menu object. 

MOVE "Fl (or esc-q) = quit" TO trailers(l). 
MOVE "MULTICS MAIL" TO headers(l). 

CALL "cb_menu_$ create" USING choi ces-tabl el , headers-table, 

- trailers-table, menu- format, keys-table, menu-needsl, 

- menu-idl, ret-code. 

IF ret-code EQUAL TO zero GO TO CREATE-SECOND-MENU. 

CALL "com_err_" USING ret-code, me, " (calling cb_menu_$create) " . 

GO TO STOP- IT. 

CREATE-SECOND-MENU. 

* Create second menu object. 

MOVE "Fl (or esc-q) = quit; F2 (or esc-f) = first menu" TO trailers (1). 
MOVE "READ MAIL" TO headers(l). 

CALL "cb_menu_$create" USING choi ces-tabie2, headers-table, 

- trailers-table, menu-format, keys-table, menu-needs2, 

- menu-id2, ret-code. 

IF ret-code EQUAL TO zero GO TO CREATE-TH I RD-MENU . 

CALL "com_err_" USING ret-code, me, " (calling cb_menu_$create) " . 

GO TO STOP- IT. 

CREATE-TH I RD-MENU. 

« Create third menu object. 

MOVE "SEND MAIL" TO headers (1) . 

CALL "cb_menu_$create" USING choi ces-tabl e3, headers-table, 

- trailers-table, menu-format, keys-table, menu-needs3» 

- menu-id3» ret-code. 

IF ret-code EQUAL TO zero GO TO STORE-MENU. 

CALL "com_err_" USING ret-code, me, " (calling cb_menu_$create) " . 
GO TO STOP- IT. 

STORE-MENU. 
MOVE ">udd>m>ri" TO dir-name. 
MOVE "menu_seg" TO entry-name. 
MOVE "cb_test_menu_" TO menu-name. 

MOVE 1 TO create-seg. 
CALL "cb_menu_$ store" USING dir-name, entry-name, menu-name, 

- create-seg, menu-idl, ret-code. 

IF ret-code EQUAL TO zero GO TO DISPLAY-IT. 

CALL "com_err__" USING ret-code, me, "(calling cb_menu_$ store) " . 
GO TO STOP- ST. 

DISPLAY-IT. 
MOVE -1 TO curr-wi ndow-id. 
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* Setting curr-wi nd-id to means that there is no current window 

* defined. 

MOVE menu-idl TO menu- id. 

MOVE lines-needed! TO lines-needed, 

DISPLAY-FIRST-MENU. 

PERFORM CHANGE-MENU THRU GOBACK. 

* The user i/o window has been "shrunk", the window for the first 

menu 

* has been created, and the first menu has been displayed. 

MOVE window- id TO window-idl. 
IF ret-code EQUAL TO zero GO TO GET- IT. 
CALL "com_err_" USING ret-code, me, "Internal error. 

Menu could not be displayed." 
GO TO STOP- IT. 

GET- IT. 
PERFORM GET-CHOICE. 

* Get the user input. Two values are returned. (1) fkey. If fkey 

= 1, 

» then the user entered a function key (or its equivalent escape 

* sequence). If fkey = 0 then the user has selected an option. (2) 
option. 

* If fkey = 1 then option is the function key number entered. (Fl = 

1, 

* F2 = 2, etc.). If fkey = 0, then option is the option number 

se! ected, 

* option = 1 means option 1 selected, etc. 

IF ret-code EQUAL TO zero GO TO TEST-FKEY. 

CALL "com_err_" USING ret-code, me, "Internal error. 

While getting user's choice.". 
GO TO STOP- IT. 

TEST-FKEY. 
IF fkeys EQUAL TO 1 

IF option EQUAL TO 1 

CALL "ioa_" USING "Exiting at your request." 
GO TO STOP- IT 
ELSE 

GO TO GET-IT 

ELSE 

IF option EQUAL TO 1 

MOVE menu-id2 TO menu- id 

MOVE 1 i nes-needed2 TO lines-needed 

PERFORM CHANGE-MENU THRU GOBACK 
ELSE 

MOVE menu-id3 TO menu- id 
MOVE 1 i nes-needed3 TO lines-needed 
PERFORM CHANGE-MENU THRU GOBACK. 
IF ret-code NOT EQUAL TO zero 
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CALL "com__errJ' USING ret-code, me, "Internal error. 

While trying to display menu." 
GO TO STOP- IT 
ELSE 

MOVE window- id TO window-id2. 
NEXT-GET-IT. 
PERFORM GET-CHOICE. 

IF fkeys EQUAL TO zero GO TO CH0SE-0PTION. 
IF option EQUAL TO 1 

CALL "ioa_" USING "Exiting at your request." 

GO TO STOP- IT 
ELSE 

IF option GREATER 2 

GO TO NEXT-GET- IT 

ELSE 

MOVE menu-idl TO menu- id 

MOVE 1 i nes-neededl TO lines-needed 

GO TO DISPLAY-FIRST-MENU. 

CHOSE-OPTION. 

r*i i II : —~ it iir i ur nv_.. _ i : ^ _i n ±. ? 

on i_ i_ i \ja ujiiiu i uu tnuac upnuii u. , upiiuiu 

GO TO NEXT-GET- IT. 
GET-CHOICE. 

CALL "cb_menu_$get_choi ce" USING window- id, menu- id, 
- f unct i on-key- i nfo, fkeys, option, ret-code. 



CHANGE-MENU. 



* Destroy the current menu window. 
IF (curr-window-id ) EQUAL TO -1 GO TO CHANGE-USER-WIND. 
CALL "cb_wi ndow_$destroy" USING curr-window-id. ret-code. 

IF ret-code EQUAL TO zero GO TO CHANGE-USER-WIND. 
GO TO GOBACK. 

CHANGE-USER-WIND. 
COMPUTE first- line = lines-needed + 1. 
COMPUTE height = user-wi ndow- 1 i nes - lines-needed. 
CALL "cb_wi ndow_$change" USING user-wi ndow- i d , first-line, height, 

- ret-code. 

IF ret-code EQUAL TO zero GO TO CREATE-NEW-WI ND 
ELSE GO TO GOBACK. 
CREATE-NEW-WI ND . 
MOVE "menu-window" TO switch-name. 

MOVE 1 TO first-line. 
CALL "cb_window_$ create" USING first-line, lines-needed, 

- switch-name, window- id, ret-code. 

IF ret-code EQUAL TO zero GO TO DISPLAY-MENU 
ELSE GO TO GOBACK. 
D i SPLAY-MENU . 

MOVE window- id TO curr-window-id. 
CALL "cb_menu_$d i spl ay" USING window-id, menu-id, ret-code. 

CALL "cb window $clear window" USING user-wi ndow- i d , ret-code. 
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GOBACK. 
EXIT. 

STOP- IT. 
CALL M cb_menu_$termi nate" . 

* cb_menu_$ term i nate MUST be the last call to cb_menu_ in the 

* application. It terminates the environment set up cb_menu_$ i ni t . 

EXIT PROGRAM. 



Name; change default wdir 

The change_default_wdir_ subroutine changes the user's current default working 
directory to the directory specified. 

USAGE 

declare change__def aul t_wd i r_ entry (char (1 68), fixed bin (35)); 

call change_def aul t_wd i r_ (path, code); 

ARGUMENTS 

path 

is the pathname of the directory that is to become the default working directory. 
(Input) 

code 

is a storage system status code. (Output) 
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Name: change_wdir 

The change_wdir_ subroutine changes the user's current working directory to the 
directory specified. 

USAGE 

declare change_wdir_ entry (char (168), fixed bin (35)); 

call change_wdir_ (path, code); 

ARGUMENTS 

path 

is the absolute pathname of the directory that is to become the user's working 
directory. (Input) 

code 

is a storage system status code. (Output) 



Name: char offset 

This function returns the character offset (relative to the base of the segment) of the 
character located by the supplied pointer value. 

USAGE 

del char_offset_ entry (ptr) returns (fixed bin (21)) reducible; 

character_of f set = char_offset_ (poi nter_val ue) ; 

ARGUMENTS 

pointer_value 

is a pointer whose character offset is to be determined. (Input) 

character_offset 

is the character offset of the supplied pointer. (Output) 

NOTES 

The first character in a segment has a character offset of zero. 

If the pointer supplied to char_offset_ does not point to a character boundary, the 
offset returned is that of the character containing the bit located by the pointer. 
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Name: char to numeric 

The char_to_numeric_ subroutine converts a user-supplied string to a numeric type, or 
signals the conversion condition if it cannot be converted. The attributes of the 
numeric data created are returned. 

USAGE 

declare char_to_numer i c_ entry (ptr, fixed bin (35). fixed bin(35)» ptr, 
fixed bin(21)) ; 

call char_to_numer i c_ (target_ptr , enc_type, enc_prec, source_ptr, 
source_len) ; 

ARGUMENTS 

target_ptr 

points to a buffer where the numeric data may be written. No check is made 
that the buffer is large enough to hold the data. (Input) 

enc_type 

is the encoded type of the data created. Its value is 2*M+P, where M is a 
standard Multics type code, and P is 1 if the data is packed, or 0 if it is not. 
(P should always be 0.) The value of Multics type codes are defined in the 
Programmer's Reference Manual. (Output) 

enc_prec 

is the encoded precision of the data created. The format of an encoded precision 
is given by encoded_precision.incl.pll. See the description of the assign, 
subroutine. (Output) 

source_ptr 

points to the character string to convert to numeric. (Input) 
source_len 

is the number of characters in the input string. (Input) 
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Name: check gate access 

This subroutine will allow a caller to determine whether a user has access to a gate 
before trying to call it. It will differentiate between not finding the gate and not 
having access. 

USAGE 

del check_gate_access_ entry (char (*) , ptr, fixed bin (35)); 
call check_gate_access_ (gate_name, ref_ptr, code); 
ARGUMENTS 
gate_name 

is the name of the gate, (e.g., "phcs_") 
ref_ptr 

is a pointer used to determine the desired referencing directory. (Input) It can be 
null (}, m which case the referencing_dir search rule is not used, or can be a 
pointer to a procedure, usually the caller of check_gate_access_, whose containing 
directory will be used as the referencing directory. 

code 

is a standard system status code. (Output) It's value will be zero if the gate is 
located using the search rules of the current ring and if the access to the gate 
includes execute access. If the gate cannot be located, the error code returned is 
error_table_$noentry. If the gate is located, but execute access is lacking, then 
error_table_$moderr is returned. 

NOTES 

Programs which can take alternate paths based on the access of lack of access to a 
gate should use this subroutine rather than trying to reference the gate explicitly and 
generating an access violation audit message in the process. 
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Name: check star name 

The check_star_name_ subroutine analyzes a character string to be sure that it has 
been formed according to the rules of the star convention, and optionally checks that 
it also conforms to the rules for forming entrynames. It returns a starname type code 
that indicates whether the string is a starname, and whether the starname matches 
every possible name. 



Entry: check star name $check star name 

This entrypoint accepts a character string and a bit mask as its inputs, and analyzes 
the character string according to the tests selected by the bit mask. 

USAGE 

declare check_star_name_ entry (char (*) , bit (36) aligned, fixed bin (2), 
fixed bin (35)) ; 

call check_star_name_ (starname, control_mask, type, code); 

ARGUMENTS 

starname 

is the character string to be analyzed. Trailing spaces in the character string are 
ignored. (Input) 

control_mask 

is a bit string constructed from constants listed below. (Input) 

type 

is one of the starname type codes listed below. (Output) 

code 

is one of the standard status codes listed below. (Output) 
LIST OF CONTROL_MASK CONSTANTS 

These constants are defined in check_star_name.incl.pll, and can be combined in most 
cases using a PL/ 1 boolean or operator (|). 

CHECK_STAR_IGNORE_ARCHIVE 

permit the archive component pathname delimiter, double colon ("::") in the 
starname, and treat it as a pair of nonspecial characters. By default, this would 
be rejected. 

CHECK_STAR_IGNORE_ENTRYPOINT 

permit the entrypoint convention delimiters, dollar sign ("$") and vertical bar ("|") 
in the starname, and treat them as nonspecial characters. By default, they would 
be rejected. 
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CHECK_STAR_IGNORE_EQUAL 

permit the equal convention characters, equal sign ("=") and percent sign ("%") in 
the starname, and treat them as nonspecial characters. By default, they would be 
rejected. 

CHECK_STAR_IGNORE_LENGTH 

permit an entryname starname or a component name starname to be more than 32 
characters long. By default, this is not permitted. The containing dir and 
entrypoints of path are not checked for length. 

CHECK_STAR_IGNORE_NONASCII 

permit nonASCII characters in an entryname starname or a component name 
starname, and treat them as nonspecial characters. By default, they would be 
rejected. 

CHECK_STAR_IGNORE_NULL 

permit null components in the starname. By default, they would be rejected. 

CHECK_STAR_IGNORE_PATH 

permit the pathname delimiters, less than ("<") and greater than (">") in the 
starname, and treat them as nonspecial characters. By default, they would be 
rejected. 

CHECK_STAR_PROCESS_ARCHIVE 

if the archive component pathname delimiter is present, analyze the substring 
preceding it and the substring following it separately. If either name is a 
starname, indicate that the match procedure must be used. A second archive 
delimiter will be rejected. If this is combined with 
CHECK_STAR_PROCESS_ENTRYPOINT, an archive delimiter following the 
entrypoint delimiter will be rejected. 

CHECK_ST AR_PROCESS_ENTR YPOI NT 

if one of the entrypoint convention delimiters is present, check the substring 
preceding it and the substring following it separately. If either name is a 
starname, indicate that the match procedure must be used. A second entrypoint 
delimiter will be rejected. If it is combined with CHECK_STAR_PROCESS_ARCHIVE, 
an entrypoint delimiter preceding the archive delimiter will be rejected. 

CHECKJSTAR_PROCESS„PATH 

if pathname delimiters are present, analyze only the substring following the 
rightmost pathname delimiter. If this string is of zero length, report that PL/ 1 
comparison can be used, because the expanded pathname will end in the name of 
a directory, and valid directory names can't contain star convention characters. 
(This is intended for names like "<". Names like ">udd>" may be rejected by 
expand_pathname_, but are acceptable to check_star_name_.) 

CHECK_STAR_REJECT_WILD 

return error_table_$nostars if any star convention characters are presents 
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error_table_$badequal 

equal convention characters were found and the control_mask did not permit 
them. 

error_table_$badpath 

the directory name contains a nonASCII character and 
CHECK_STAR_PROCESS_PATH was specified but 

CHECK_STAR_IGNORE_NONASCII was not 

error_table_$badstar 

the string violates the rules for forming starnames. 

error_table_$entlong 

The string was more than 32 characters long and the control_mask did not permit 
it. If CHECK_STAR_PROCESS_PATH was specified, the entryname part of the 
string was more than 32 characters long. If CHECK_STAR_PROCESS_ARCHIVE 
was specified, either the entryname or the component name was more than 32 
characters long. 

error_table_$inconsistent 

the control_mask was in error, specifying both CHECK_STAR_PROCESS and 
CHECK_STAR_IGNORE the same test 

error_table_$invalid_ascii 

the entryname contains a nonASCII character and 
CHECK_STAR_IGNORE_NONASCII was not specified. 

error_table_$nostars 

stars or question marks were found and CHECK_STAR_REJECT_WILD was 

specified in the control_mask. Note that star_type will correctly reflect the 
starname type for this case. 

error_table_$null_name_component 

the string contains null components and the control_mask did not permit them. 

NOTES 

See the description of the hcs_$star_ entrypoint in hcs_ to find how to list the 
directory entries that match a given starname. See match_star_name_ to find how to 
match a starname with an entryname. See starname. gi. info for the rules governing the 
formation and interpretation of starnames. See entryname.gi.info for the rules 
governing the formation of entrynames. 
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Entry: check star_name Sentry 

This entrypoint accepts the entryname to be analyzed as input. 

USAGE 

declare check_star_name_$entry entry (char (*) , fixed bin(35))» 

call check_star_name_$entry (entryname, code); 

ARGUMENTS 

entryname 

is the entryname to be validated. Trailing spaces in the entryname character string 
are ignored. (Input) v 

code 

is one of the nonstandard status codes listed below. (Output) 
LIST OF STATUS CODES 
0 

the entryname is valid and is not a starname (does not contain asterisks or 
question marks). 

1 

the entryname is valid and is a starname (does contain asterisks or question 
marks). 

2 

the entryname is valid and is a starname that matches every entryname. 
error_table_$badstar 

the entryname is invalid. It violates the rules for forming starnames, or it violates 
the rules for constructing entrynames. 

NOTES 

This entrypoint is obsolete. Use the check_star_name_ entrypoint for new applications. 
The new entrypoint returns a variety of different standard error codes explaining a 
rejection whereas this entrypoint can only return a single standard error code value 
for compatability. 

See the description of the hcs_$star_ entrypoint in hcs_.info to find how to list the 
directory entries that match a given starname. See match_star_name_.info to find how 
to match a starname with an entryname. See starname. gi.info for the rules governing 
the formation and interpretation of starnames. See entryname. gi. info for the rules 
governing the formation of entrynames. 
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Entry: check__star name $path 

This entrypoint accepts a pathname as its input and analyzes the final entryname in 
that pathname. 

USAGE 

declare check_star_name_$path entry (char (*) , fixed bin (35)); 

call check_star_name_$path (path, code); 

ARGUMENTS 

path 

is the pathname whose final entryname is to be validated. Trailing spaces in the 
pathname character string are ignored. (Input) 

code 

is one of the nonstandard status codes listed below. (Output) 
LIST OF STATUS CODES 
0 

the entryname is valid and is not a starname (does not contain asterisks or 
question marks). 

1 

the entryname is valid and is a starname (does contain asterisks or question 
marks). 

2 

the entryname is valid and is a starname that matches every entryname. 
error_table_$badstar 

the entryname is invalid. It violates the rules for forming starnames, or it violates 
the rules for forming pathnames. 

NOTES 

This entrypoint is obsolete. Use the check_star_name_ entrypoint for new applications. 
The new entrypoint returns a variety of different standard error codes explaining a 
rejection whereas this entrypoint can only return a single standard error code value 
for compatibility. 

See the description of the hcs_$star_ entrypoint in hcs_ to find how to list the 
directory entries that match a given starname. See match_star_name_ to find how to 
match a starname with an entryname. See starname. gi. info for the rules governing the 

formation and interpretation of starnames. See pathname.gi.inf o for the rules governing 
the formation of pathnames. 
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Name: clock_ 

The clock_ function reads the system clock and returns a fixed binary number equal 
to the number of microseconds since 0000 hours Greenwich mean time January 1, 
1901. The returned time is suitable for input to the date_time_ or decode_clock_value_ 
subroutines, which convert the clock reading to an ASCII representation, or decompose 
it into its component parts, respectively. 

USAGE 

declare clock_ entry returns (fixed b i n (7 1 ) ) ; 

date_time - clock_ () ; 

ARGUMENTS 

date_time 

is the number of microseconds since January 1, 1901, 0000 hours Greenwich mean 
time. (Output) 

NOTES 

The clock PL/ 1 builtin function should be used in PL/ 1 programs instead of this 
subroutine, because it is more efficient. 
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CHECK_STAR_IGNORE_ALL 

combines all the CHECK_STAR_IGNORE flap. This can be used to analyze a 
starname to determine its type without applying any of the tests intended for 
validating entrynames. 

CHECK_STAR_ENTRY_DEFAULT 

combines exactly the same tests used by the obsolete check_star_name_$entry 
entrypoint, which is equivalent to combining CHECK_STAR_IGNORE_ENTRYPOINT 
and CHECK_STAR_IGNORE_EQUAL. 

CHECK_STAR_PATH_DEFAULT 

combines exactly the same tests used by the obsolete check_star_name_$path 
entrypoint, which is equivalent to combining CHECK_STAR_PROCESS_ARCHIVE, 
CHECK_STAR_IGNORE_ENTRYPOINT, CHECK_STAR_IGNORE_EQUAL, and 
CHECK_STAR_PROCESS_PATH. 

LIST OF STARNAME TYPE CODES 

These type constants are defined in check_star_name.incl.pll. 

STAR_TYPE_MATCHES_EVERYTHING (2) 

no comparison is necessary, since the starname matches all possible strings. 

STAR_TYPE_USE_MATCH_PROCEDURE (1) 

the procedure match_star_name_ must be used to compare the string to possible 
matching strings, because it is a starname containing stars (asterisks) and question 
marks. 

STAR_TYPE_USE_PLl_COMPARE (0) 

the string is not a starname and can be compared using PL/ 1 comparison rules. 

LIST OF STATUS CODES 



the string passes all of the selected tests, and the starname type output indicates 
whether the string is a starname. 

error_table_$archive_pathname 

the archive component pathname delimiter was found, and the control_mask did 
not permit it. 

error_table_$bad_arg 

the control mask specified an unimplented test 

error_table_$bad_f ile_name 

the string violates the rules for forming entrynames and the control_mask did not 
permit it. 
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Name: com err 

The com_err_ subroutine is the principal subroutine used by commands for printing 
error messages. It is usually called with a nonzero status code to report an unusual 
status condition. It can also be called with a code of 0 to report an error which does 
not have a status code associated with it Status codes are described in the 
Programmer's Reference Manual. 

See also the active_fnc_err_ subroutine which should be used by active functions for 
printing error messages. 

The com_err_ entry point formats an error message and then signals the command_error 
condition. The default handler for this condition simply returns control to the 
com_err_ subroutine, which then writes the error message on the error_output I/O 
switch. 

USAGE 

declare com_err_ entry options (variable); 

call com_err_ (code, caller, control_str i ng, argl, argN) ; 

ARGUMENTS 

code 

is a standard status code, which normally is fixed binary (35), but can be any 
computational data type. (Input) If it is not already fixed binary (35), it will be 
converted to fixed binary (35). 

caller 

is the name (char(*)) of the procedure calling the com_err_ subroutine. (Input) It 
can be either varying or nonvarying. 

control_string 

is an ioa_ subroutine control string (char(*)). (Input) This argument is optional 
(see "Notes" below). 

argl 

are ioa_ subroutine arguments to be substituted into the control_string argument. 
(Input) These arguments are optional. They can only be used, however, if the 
control_string argument is given first (see "Notes" below). 

NOTES 

The error message prepared by the com_err_ subroutine has the following format 
caller: system_message userjnessage 
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where: 
caller 

is the name of the program detecting the error. 
system_message 

is a standard message from the error table corresponding to the value of code. If 
code is equal to 0, no system_message is printed. 

user_message 

is constructed by the ioa_ subroutine from the control_string and argl arguments. 
If the control_string and argl arguments are omitted, no user_message is printed. 

If code is error_table_$active_f unction, com_err_ will print a slightly different message 
and signal the active_function_error condition to prevent the command from being 
restarted. The message printed will be: 

caller: This command cannot be invoked as an active function. 
user_message 

error: At tempt to invoke command caller as an active function. 

If the com_err_ subroutine is passed a nonzero code that does not correspond to a 
standard format error table entry, the system_message is of the form: 

Code ddd 

where ddd is the decimal representation of code. The argument caller must not be 
null or blank; if it is, the handlers for command_error cannot identify the signalling 
procedure. 



Entry: com err Ssuppress name 

This entry point should be used when the caller name and colon are not wanted. The 
caller name is still passed to the command_error condition handler. Otherwise, this 
entry point is the same as the com_err_ entry point 

USAGE 

declare com_err_$suppress_name entry options (variable); 

call com_err_$suppress_name (code, caller, control_str i ng, argl, 
argN) ; 
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ARGUMENTS 

All of the arguments are the same as in the com_err_ entry point. 



Name: command query 

The command_query_ subroutine is the standard system procedure invoked to ask the 
user a question and to obtain an answer. It formats the question and then signals the 
condition command_question. System conditions are described in the Programmer's 
Reference Manual. The default handler for this condition simply returns control to 
the command_query_ subroutine, which writes the question on a specified I/O switch. 
It then reads from another I/O switch to obtain the answer. Several options have 
been included in the commmand_query_ subroutine to support the use of a more 
sophisticated handler for the command_question condition. 

Since this procedure can be called with a varying number of arguments, it is not 
permissible to include a parameter attribute list in the declaration. 

USAGE 

declare comma nd_query_ entry options (variable); 

call command_query_ (info_ptr, answer, caller, control_str i ng, 
argl , . . . , argN) ; 

ARGUMENTS 

info_ptr 

is a pointer to the query_info structure described in "Info Structure" below. 
(Input) 

answer 

is the response (char(*) or char (*) varying) read from the I/O switch user_input. | 

(Output) Leading and trailing blanks plus the newline character have been 
removed. 

caller 

is the name (char(*)) of the calling procedure. (Input) It can be either varying or 
nonvarying. 

control_string 

is an ioa_ subroutine control string (char(*)). (Input) This argument is optional. 
See "Notes" below. 

argi 

are ioa_ subroutine arguments to be substituted into control_string. (Input) These 
arguments are optional. They can only be used if the control_string argument is 
given first. See "Notes" below. 
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INFO STRUCTURE 



The following is the query_info structure (found in the include file query _info.incl.pll): 

del 1 query_info aligned, 

2 version fixed bin, 

2 swi tches al i gned, 

3 yes_or_no_sw bit(l) unaligned, 

3 suppress_name_sw bit(l) unaligned, 

3 cp_escape_control bit (2) unaligned, 

3 suppress_spaci ng bit(l) unaligned, 

3 literal_sw bit(l) unaligned, 

3 prompt_after explanation 

bit (1) unal i gned, 

3 padding bit (29) unaligned, 

2 status_code fixed bin (35). 

2 query_code fixed bin(35)» 

2 quest ion_iocbp ptr, 

2 answer_iocbp ptr, 

2 repeat_time fixed bin (71), 

2 explanat ion_ptr ptr, 

2 explanation_len fixed bin (21); 



STRUCTURE ELEMENTS 



version 

is the version number of this structure. (Input) The version number must be set 
by the caller and identifies the format of the structure. The current version is a 
static variable named query_info_version_6 in query_info.incl.pll. 

yes_or_no_sw 

indicates whether an answer of a particular form is expected. (Input) 

"0"b accepts any answer. 

*T*b accepts only a yes or no answer. 



suppress_name_sw 

controls whether the name of the calling procedure appears in the question. 
(Input) 

"0"b includes name and following colon. 
"l"b omits name and colon. 



cp_escape_control 

controls whether the command_processor_ escape mechanism is enabled for this 
call. (Input) 

"00"b obeys the static default. 

"01"b allows lines to begin with but does not interpret them as 

command processor escapes. 
"10"b disallows escape, ignores default 
"ll"b allows escape, ignores default. 
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suppress_spacing 

controls the insertion of a newline before the question and two spaces after it 
(Input) 

"0"b inserts extra space. 
"l"b omits extra space. 

literal_sw 

is 'T'b to suppress any special interpretation of characters (for example, "..") and 
suppress stripping of leading whitespace. 

prompt_af ter_explanation 

is 'T'b to repeat the original question after printing any explanation indicated by 
a non-null explanation argument 

padding 

is unused space. (Input) 

status_code 

is either the standard status code that prompted the question or 0. (Input) 
query_code 

is additional arbitrary qualifying information passed by the caller of command_query_. 
(Input) It is intended for use by specialized handlers for command_question. 

question_iocbp 

is an iocb pointer for the I/O switch over which the caller wants the question to 

be written. (Input) A null pointer indicates that the of the user_i/o switch is to 
be used by default. 

answer_iocbp 

is an iocb pointer for the I/O switch from which the caller wants the answer to 
be read. (Input) A null pointer indicates that the user_input switch is to be used 
by default. 

repeat_time 

is the number of seconds to wait for an answer before repeating the question on 
the switch pointed to by question_iocbp. (Input) A value less than 30 indicates 
that the question is not to be repeated. 

explanation_ptr 

is a pointer to a string to be printed if the user answers "?". (Input) 

explanationjen 

is the length of the explanation string. (Input) 
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NOTES 

The question prepared by the command_query_ subroutine has the format 
caller: message 

where the message is constructed by the ioa_ subroutine from the control_string and 
argN arguments. If the control_string and argN arguments are not given, the message 
portion of the question is omitted. 

If the user answers with a single question mark (?), the explanation_ptr field is 
examined. If it is non-null and explanation_len is greater than 0, the explanation 
string pointed to is printed and the user is expected to answer again. Otherwise, the 
string "Answer: " is printed and the user is expected to answer again. 

| Case insensitive "yes", "y", and "n" are acceptable responses to a yes or no question. 

In an absentee process with the yes_or_no_sw on, an answer other case insensitive 
"yes", "y", "no", "n", or "?" causes the absentee process to signal command_query_error. 

If the answer to a question begins with and the cp_escape feature is enabled for 
the question, the rest of the answer following the ".." is passed to the command 
processor. Control then returns to command_query_, which prompts with "Answer: " 
after the command has been executed. The cp_escape feature is normally enabled in 
the standard Multics environment; a subsystem, however, can elect to turn it off, 
either globally or for a particular question. The prompt of "Answer: " is used rather 
than repeating the question because the question may be quite long and take significant 
time to print If it is necessary to see the question again, answering "..repeat_query" 
repeats it. 



Entry: command query $set cp escape enable 

This entry sets the static default switch that allows or disallows the command 
processor escape feature. It also returns the previous value for the switch. Since 
escapes are disabled initially, it is necessary to call this entry to enable the feature. 
This entry is called by process_overseer_, which sets it so that the escape is permitted 
in a normal Multics environment. 

USAGE 

declare command_query_$set_cp_escape_enabl e entry (bit(l) aligned, 
bit ( 1 ) al i gned) ; 

call command__query_$set_cp_escape_enabl e (new__value, old_value) ; 
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ARGUMENTS 
new_value 

is the new value for the default. (Input) 
"0"b feature is disabled by default 
"l"b feature is enabled by default 



old_value 

is the old value of the default. (Output) If it has never been set, it is "0"b. 



Entry: command query_$yes no 

This entry asks the user for a yes or no answer. 
USAGE 

del command_query__$yes_no entry options (variable); 

call command_query_$yes_no (yes_sw, query_code, caller, explanation, 
question, argl, argN) ; 

ARGUMENTS 

yes_sw 

is a bit (1) return value, ON for "yes" or "y" and OFF for "no" or "n", case 
insensitive. (Output) Other answers are not accepted from the user. 

query_code 

is a standard status code. (Input) If it is nonzero, the question is preceded by 
the corresponding error message. 

caller 

is the character string name of the calling program. (Input) 
explanation 

is an explanation of the question, printed when the user answers "?". (Input) The 
explanation is an ioa_ control string, in which parameters are replaced by the 
values of the argN arguments. For a description of control strings, see the ioa_ 
subroutine. 

question 

is the question, also in the form of an ioa_ control string. (Input) Parameters are 
replaced by the same argN arguments as for the explanation. 

argN 

are character string arguments to the ioa_ control strings specified by explanation 
and question. (Input) 
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NOTES 

The same arguments are substituted in both explanation and question control strings. 
Each control string can use A s to skip particular arguments. 

EXAMPLES 

The following shows a use of the explanation argument 

call command_query_$yes__no (yes__sw, 0, "delete_noti f ications", 

"Do you want to delete all messages that have been printed?", 
"Delete?"); 

This call produces the following behavior when the user answers "?": 
delete_notif ications: Delete? ? 

Do you want to delete all messages that have been printed? yes 

The following explanation and question use parameter substitution and a nonzero 
query_code argument: 

ral 1 rnmmanH nnprv ^ voc nn 
— ■ ■ — -i / / — — 

(yes__sw, error_tabl e_$namedup, "create_tf f " , 

"Do you want to delete the old ~a "a before creating a new one?" 
"Delete old ~s^a?", "segment", pathname); 

producing the following: 

create__tff: Name duplication. Delete old >udd>d>c>h . tf f ? ? 
Do you want to delete the old segment >udd>d>c>h . tf f before 
creating a new one? yes 



Name: component info___ 

This subroutine returns information about a component of a bound segment similar to 
that returned by object_info_. The component may be specified either by name or by 
offset. 
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Entry: component info Sname 

This entry point specifies the component by name. 
USAGE 

declare component_i nf o $name entry (ptr, char (32) aligned, ptr, 
fixed bin (35)) ; 

call component^ nf o_$name (seg_ptr, comp_name, arg_ptr, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the bound segment 

comp_name 

is the name of the component. 

arg_ptr 

is a pointer to a structure to be filled in (see "Notes" below). 

code 

is a standard status code. (Output) 



Entry: component info $offset 

This entry point specifies the component by its offset 
USAGE 

declare component^ nf o_$of f set entry (ptr, fixed bin(l8), ptr, 
fixed bin (35)) ; 

call component_i nf o_$of f set (seg_ptr, offset, arg_ptr, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the bound segment (Input) 
offset 

is an offset into the bound segment corresponding to the text, internal static or 
symbol section of some component. (Input) 

arg_ptr 

is a pointer to a structure to be filled in (see "Notes" below). 

code 

is a standard status code. (Output) 
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NOTES 

The structure to be filled in (a declaration of which is found in component_info.incl.pll) 
is declared as follows: 



c i 




a 1 i gned , 


2 


dc 1 vers i on 


f i xed b j n, 


2 


name 


char (32) al igned, 


2 


text start 


Dtr . 


2 


stat start 


Dtr . 


2 


symb start 


d tr . 


2 


defblock Dtr 


Dtr . 


2 


text 1 na 


f i xed bin, 


2 


stat 1 ng 


f i xed bin, 


2 


symb_l ng 


fixed bin, 


2 


n_b locks 


fixed bin, 


2 


standard 


bi t (1) al igned, 


2 


compi ler 


char (8) al i gned, 


2 


comp i 1 e_t i me 


fixed bi n (71) , 


2 


user_i d 


char (32) al i gned, 


2 


cvers 


al i gned, 




~i offset 


bit(l8) una! igned - 




3 length 


bit ( 1 8) unaligned, 


2 


comment 


al i gned, 




3 offset 


bit ( 1 8) unal igned, 




3 length 


bit ( 1 8) unal igned, 


2 


source_map 


fixed bin; 



STRUCTURE ELEMENTS 
dcl_version 

is the version number of this structure. It is set by the caller and must be 1. 
name 

is the name of the component, i.e., the name specified in a bindfile objectname 
statement; also, the name of the component as archived. 

text_start 

is a pointer to the base of the component's text section. 
stat_start 

is a pointer to the base of the component's internal static. 
symb_start 

is a pointer to the base of the component's symbol section. 
defblock_ptr 

is a pointer to the component's definition block, 
textjng 

is the length, in words, of the component's text section. 
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stat_lng 

is the length, in words, of the component's internal static, 
symbjng 

is the length, in words, of the component's symbol section. 
n_blocks 

is the number of blocks in the component's symbol section, 
standard 

is on if the component is in standard object format 
compiler 

is the name of the component's compiler, 
compilejime 

is a clock reading of the date/ time the component was compiled. 
user_id 

is the standard Multics User_id of the component's creator, 
cvers. offset 

is the offset of the printable version description of the component's compiler, in 
words, relative to symb_start 

cvers. length 

is the length, in characters, of the component's compiler version, 
comment, offset 

is the offset of the component's compiler comment, in words, relative to 
symb_start 

commentlength 

is the length, in characters, of the component's comment. 

source_map 

is the offset of the component's source map structure, in words, relative to 
symb_start. 
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Name: compute common aim ceiling 

This subroutine computes the maximum authorization or access class which is in 
common between two Multics systems given the definitions of their AIM attributes. 

USAGE 

declare compute_common_a im_cei 1 i ng_ entry (ptr, b i t (72) aligned, ptr, 
bit (72) aligned, f i xed b i n (35) ) ; 

call compute_common_aim_cei 1 i ng__ (aim__attr i butes_l_ptr , 

common_cei 1 i ng_l , aim_attr ibutes_2_ptr , common_ceil i ng_2, code); 

ARGUMENTS 

aim_attributes_l_ptr 

is a pointer to the aim_attributes structure defining the AIM attributes of the 
first system. (Input) This structure is declared in aim_attributes.incl.pll. 

common_eeiling_l 

is set to the maximum authorization or access class in common between the two 
systems in terms of the AIM attributes of the first system. (Output) 

aim_attributes_2_ptr 

is a pointer to the aim_attributes structure defining the AIM attributes of the 
second system. (Input) 

common_ceiling_2 

is set to the maximum authorization or access class in common between the two 
systems in terms of the AIM attributes of the second system. (Output) 

code 

is a standard system status code. (Output) It can be one of the following: 
0 

the common access ceiling was successfully computed. 
erroT_table_$unimplemented_version 

one of the aim_attributes structures supplied by the caller was of a version 

not supported by this procedure. 
error_table_$ai_no_common_max 

there is no set of AIM attributes in common between the two systems. 

NOTES 

See the description of the get_system_aim_attributes_ subroutine for a definition of 
the aim_attributes structure. 

See the Programmers' Reference Manual for a definition of common access ceiling. 
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Name: condition 

This subroutine establishes a handler for a condition in the calling block activation if 
a handler for the specified condition is currently established in the calling block. 

A description of the condition mechanism is given in the Multics Programmer's 
Reference manual in the section entitled "The Multics Condition Mechanism". 

USAGE 

declare condition_ entry (char (*) , entry); 
call condition_ (name, handler); 
ARGUMENTS 
name 

is the name of the condition for which the handler is to be established. (Input) 
handler 

is the handler to be invoked when the condition is raised. (Input) 
NOTES 

The condition name unclaimed_signal is an obsolete special condition name and should 
not be used. 

The PL/ 1 on statement and the condition, subroutine must not be- invoked during the 
same block activation in order to establish a handler for the same condition. 

In PL/ 1 Version 2, when a call to condition, appears within the scope of a begin 
block or internal procedure of a procedure, the no_quick_blocks option must be 
specified in the procedure statement of that procedure. The no_quick_blocks option is 
a nonstandard feature of the Multics PL/I language and, therefore, programs using it 
may not be transferable to other systems. 
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Name: condition interpreter^. 

The condition_interpreter_ subroutine can be used by subsystem condition handlers to 
obtain a formatted error message for all conditions except quit, alrm, and cpuL Some 
conditions do not have messages and others cause special actions to be taken. These 
are described in "Notes" below. (For more information on conditions, see the 
Programmer's Reference Manual.) 

USAGE 

declare cond i t i on_i nterpreter_ entry (ptr, ptr, fixed bin, fixed bin, 
ptr, char (*) , ptr, ptr) ; 

call condi t ion_i nterpreter_ (area_ptr, m_ptr, mlng, mode, mc_ptr, 
cond_name, wc_ptr, i nf o_ptr) ; 

ARGUMENTS 

area_ptr 

is a pointer to the area in which the message is to be allocated, if the message is 
to be returned. The area size should be at least 300 words. If null, the message 
is printed on the error_output I/O switch. (Input) 

m_ptr 

points to the allocated message if area_ptr is not null; otherwise it is not set. 
(Output) 

mlng 

is the length (in characters) of the allocated message if area_ptr is not null. If 
area_ptr is null, the length is not set Certain conditions (see "Notes" below) have 
no messages; in these cases, mlng is equal to 0. (Output) 

mode 

is the desired mode of the message to be printed or returned. (Input) It can 
have the following values: 

1 normal mode 

2 brief mode 

3 long mode 

mc_ptr 

if not null, points to machine conditions describing the state of the processor at 
the time the condition was raised. (Input) 

cond_name 

is the name of the condition being raised. (Input) 
wc_ptr 

is usually null; but when mc_ptr points to machine conditions from ring 0, 
wc_ptr points to alternate machine conditions. (Input) 
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info_ptr 

if not null, points to the information structure described in the Programmer's 
Reference Manual. (Input) 

NOTES 

The following conditions cause a return with no message: 

command_error 
command_question 
finish 
stringsize 



Name: continue to signal 

The continue_to_signal_ subroutine enables an on unit that cannot completely handle a 
condition to tell the signalling program, upon its return, to search the stack for other 
on units for the condition. The search continues with the stack frame immediately 
preceding the frame for the block containing the on unit However, if a separate on 
unit for the any_other condition is established in the same block activation as the 
caller of the continue_to_signal_ subroutine, that on unit is invoked before the stack 
is searched further. 

USAGE 

declare cont i nue_to_s i gnal_ entry (fixed bin (35)); 

call cont i nue_to_s i gna 1_ (code); 

ARGUMENTS 

code 

is a standard status code and is nonzero if continue_to_signal_ was called when 
no condition was signalled. (Output) 
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Name: convert access audit flags 

This subroutine is provided to convert a security audit flag back and forth between its 
character string representation and the internal binary representation. 



Entry: convert access_audit f lags_$f rom string 

This entry point converts the textual representation to internal representation. 
USAGE 

del convert_access_aud i t_f 1 ags_$f rom_str i ng entry (char (*) , bit (36) 
aligned, fixed bin (35)); 

call convert_access_audi t_f 1 ags_$f rom_str i ng (flags_str, audit_flags, 
code) ; 

ARGUMENTS 

flags_str 

is the textual representation of the security audit flags. (Input) 
audit_flags 

is the bit string internal representation of the flags. (Output) 

code 

is a standard system status code. (Output) 



Entry: convert access audit flags $to string 

This entry point converts from internal representation to textual representation. 
USAGE 

del convert_access_aud i t_f 1 ags_$to__str ing (entry (char (*) , bit (36), 
aligned, fixed bin (35))*. 

call convert__access_audi t_f 1 ags_$to_str ing (flags_str, audi t_f lags, 
code) ; 

ARGUMENTS 

flags_str is the textual representation of the security audit flags. (Output) 
audit_flags 

is the bit string internal representation of the flags. (Output) 
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code 

is a standard system status code. (Output) It can have one of the following 
values: 

error_table_$badarg 

audit_flags is illegally constructed 

error_table_$smallarg 

flags_str is too small for result 

NOTES 

The format of the flags string is as follows: 
flag-string := flag-item [, flag-item] 

flag-item := object-type-keyword "grant=" audit-level -keyword 
flag-item := object-type-keyword "-deny=" audit-level-keyword 
flag-item := even-type-keyword 

object-type-keyword := "fsobj" | "fsattr" | "rep" | "admin" | 

"special" j "other" 
audit-level-keyword := "none" | "modify_access" | "modify" | "read" 
event- type-key word := "admin_op" | "priv_op" | "fault" ! 

"cc_l_10" | "cc_10_100" 

example: 

f sobj-grant=modif y ,rcp-deny =modif y_access,other-grant=none, f ault 



Name: convert access class 

The convert_access_class_ subroutine is provided to convert an access attribute in the 
Multics access isolation mechanism (AIM) back and forth between its binary and 
character-string representations. Additional entries provide the ability to encode an 
access attribute as a short character string for use in entrynames. 



Entry: convert access class $decode 

This entry point takes the character string produced by the convert_access_class_$encode 
entry point and returns the original access attribute. The null string and the string 
"system_low" are both converted to return the system_low access attribute. 

USAGE 

declare conver t_access_c 1 ass_$decode entry (bit (72) aligned, char(»)); 
call conver t_access_c 1 as s_$ decode (acc_att, decoded_str i ng) ; 
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ARGUMENTS 
acc_att 

is the the decoded authorization. (Output) 
decoded_string 

is a short string (maximum of 15 characters) that uniquely represents the input 
access attribute. (Input) 



Entry: convert access class $encode 

This entry point encodes an access attribute into a short character string, suitable for 
inclusion in entrynames. If the input access attribute represents system_low, the 
returned string is "system_low". 

USAGE 

declare conver t_access_c 1 ass_$encode (bit (72) aligned, char(*)); 
call conver t_access_c 1 ass $encode (acc_att, encoded_str i ng) ; 
ARGUMENTS 
acc_att 

is the input access attribute (Input) 
encoded_string 

is a short string (maximum of 15 characters) that uniquely represents the input 
access attribute. (Output) 



Entry: convert access class_$from__string | 

This entry point converts the character string representation of an access attribute to | 
an encoded binary form suitable for storage in system tables and as input to the 
various modules that accept the binary form. 

USAGE 

declare conver t_access_class_$f rom_str i ng entry (bit (72) aligned, 
char (*) , fixed bin (35)) ; 

call conver t_access_c 1 ass_$from_str i ng (acc_att, string, code); | 

ARGUMENTS 

acc_att | 
is the binary representation of string. (Output) 
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string 

is the character string to be converted (see "Notes" below). (Input) 

code 

is a standard status code. (Output) It can be one of the following: 

error_table_$ai_invalid_string 

one or more namei is misspelled (see "Notes" below). 

error_table_$ai_above_allowed_max 
| no error in conversion; but the resulting access attribute is greater than the 

| system_high access attribute. 

NOTES 

The string argument must be of the form: 
name 1 , name2 , . . . , nameN 

where namei represents the mnemonic for a sensitivity level or access category. The 
print_auth_names command can be used to obtain a list of acceptable mnenomics. If 
the string argument is null or system_low. the resulting authorization is level 0 and no 
categories. If the string is system_high, the system access_ceiling is returned (the 
j maximum access attribute allowed). 

| Entry: convert access class__$from string range 

| This entry point converts a character string to the form of a binary access attribute 
j range. 

USAGE 

declare convert_access_cl ass_$f rom_str i ng_range entry (bit (72) aligned 
d imens i on (2) , char (*) , fixed bin (35)); 

call convert_access_cl ass_$f rom_str i ng_range (acc_att_range, string, 
code) 
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ARGUMENTS 

acc_att_range | 
is the binary representation of string. (Output) 

string 

is the character string to be converted (see "Notes" below). (Input) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$ai_invalid_string 

one or more namei are misspelled (see "Notes" below). 
error_table_$ai_above_allowed_max 

no error in conversion; but the resulting access attribute is greater than the 

system_high access attribute. 
error_table_$ai_invalid_range 

no error in conversion; but acc_att_range (2) does not represent an access 

attribute greater than or equal to acc_att_range (1). 

NOTES 

The string must be one of the two forms: 
name 1 , name2 , . . . , nameN 

namela,name2a, . . . ,nameNa:namelb,name2b, . . .nameNb 

where namei represents the mnemonic for a sensitivity level or access category. If the 

string is in the first form, both elements of acc_att_range will be set to equal values | 

(similar to the operation of convert_access_class_$from_string). If string is in the | 

second form, acc_att_range (1) will be returned as the binary representation of the j 

part of string left of the colon, and acc_att_range (2) will be returned as the binary | 
representation of the part of the string right of the colon. 



Entry: convert access class Sminimum 

This entry point accepts an array of access attributes and a binary number indicating 
how many elements to process from the array. It returns an access attribute class 
whose category set is the intersection of all input category sets and whose sensitivity 
level is the minimum of all input sensitivity levels. The returned value need not equal 
any of the input values. 

USAGE 

declare convert_access_c 1 ass_$mi ni mum entry (dim(«) bit (72) aligned, 
fixed bin, bit (72) aligned); 

call convert_access_class_$mi nimum (acc_att_array , n_elements, 
mi nimum_acc_att) 
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ARGUMENTS 

acc_att_array 

are the input access attributes(Input) 

n_elements 

is the number of elements to be processed in the acc_att_array argument. (Input) 

minimum_acc_att 

is the result. (Output) 



I Entry: convert access class $to string 

I This entry point accepts a binary form of an access attribute and returns it as a 
printable string. This output string is suitable for input to the 
convert_access_class_$from_string entry point Each level /category name has a maximum 
length of 32 characters. 

/ /o A/nr 

declare convert_access_cl ass_$to_str i ng entry (bit (72) aligned, char (*) , 
fixed bin (35)) ; 

| call convert_access_class_$to_str i ng (acc_att, string, code); 
| ARGUMENTS 
acc_att 

is the access attribute to be converted. (Input) 
string 

is the resultant character string (see "Notes" below). (Output) 

code 

is a standard status' code. (Output) It can be one of the following: 
error_table_$smallarg 

string is too short to hold the converted result (see "Notes" below), 
error tabie_$ai_invaiid binary 

either the level number or category set is invalid; the resulting output is also 

invalid. 

| NOTES 

When the error_table_$smallarg code is returned, as much of the resulting conversion 
as fits in the output string is returned. However, since the results are not complete, 
they should not be used as input to the convert_access_ciass_$from_string entry point. 
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If the access attribute is equal to the site access ceiling as defined by the 
installation_parms and returned by system_info_$access_ceiling, then "system_high" is 
returned in the string. 



Entry: convert access class_$to string range j 

This entry point accepts a binary access attribute range pair and returns it as a | 
printable string. This output string is suitable for input to the 
convert_access_class_$from_string_range entry point Each level /category name has a 
maximum length of 32 characters. 

USAGE 

declare convert_access_c 1 ass_$ to_str i ng_range entry (bit (72) aligned 
dimension (2), char (*) , fixed bin (35)); 

call convert_access_class_$to_str i ng_range (acc_att_range, string, 
code) ; 

ARGUMENTS 

acc_att_range 

is the binary representation of an access attribute range to be converted. (Input) 
string 

is the resultant character string (see "Notes" below). (Output) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$smallarg 

string is too short to hold the converted result (see "Notes" below). 
error_table_$ai_invalid_binary 

either the level number or category set is invalid; the resulting output is also 

invalid. 

error_table_$ai_invalid_range 

no error in conversion; but acc_att_range (2) does not represent an access | 
attribute greater than or equal to acc_att_range (1). | 

NOTES 

When the error_table_$smallarg code is returned, as much of the resulting conversion 
as fits in the output string is returned. However, since the results are not complete, 
they should not be used as input to the convert_access_class_$from_string entry point. 



If either of the access attributes is equal to the site access ceiling as defined by the 
installation_parms and returned by system_info_$access_ceiling, then "system_high" is 
returned in the string for that attribute. 
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| Entry: convert access__class_$to string range__short 

This entry point is identical to the convert_access_class_$to_string_range entry point 
except that the short level /category names are returned. Each short name has a 
maximum length of eight characters. This output is also suitable for input to the 
convert_access_class_$from_string_range entry point. 

USAGE 

declare conver t_access_c 1 ass_$to_str i ng_range_shor t entry (bit (72) 
aligned d imens i on (2) , char (*) , fixed bin (35); 

call convert_access_class_$to_str i ng_range_short (acc_att_range, string, 
code) ; 

ARGUMENTS 

acc_att_range 

is the binary representation of an access attribute range range to be converted. 



string 

is the resultant character string (see "Notes" below). (Output) 

code 

is a standard status code. (Output) It may be one of the following: 
error_table_$smallarg 

string is too short to hold the converted result (see "Notes" below). 
error_table_$ai_invalid_binary 

either the level number or category set is invalid: the resulting output is also 

invalid. 

error_table_$ai_invalid_range 
j no error in conversion; but acc_att_range (2) does not represent an access 

| attribute greater than or equal to acc_att_range (1). 

| NOTES 

If either of the access attributes is equal to the site access ceiling as defined by the 
installation_parms and returned by system_info_$access_ceiling, then "system_high" is 
returned in the string for that attribute. 
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Entry: convert access class $to string short 

This entry point is identical to the convert_access_class_$to_string entry point, except 
that the short level /category names are returned. Each short name has a maximum 
length of eight characters. This output is also suitable for input to the 
convert_access_class_$from_string entry point. 

USAGE 

declare convert_access_c 1 ass_$to_str i ng_shor t entry (bit(72) aligned, 
char (*) , fixed bin (35)) ; 

call convert_access_cl ass_$to_str i ng_short (acc_att, string, code); 
ARGUMENTS 



acc_att 

is the binary representation of an access attribute to be converted. (Input) 
string 

is the resultant character string. (Output) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$smallarg 

string is too short to hold the converted result (see "Notes" below). 
error_table_$ai_invalid_binary 

either the level number or category set is invalid; the resulting output is also 

invalid. 



Name: convert__date to binary 

The convert_date_to_binary_ subroutine converts a character representation of a date 
and time into a 72-bit clock reading. It accepts a wide variety of date and time 
forms, including the output of the date_time_ subroutine. 

USAGE 

declare convert date_to binary entry (char (*) , fixed bin (71), fixed 
bin(35))T 

call convert_date_to_bi nary_ (t ime_str i ng, clock, code); 
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ARGUMENTS 
time_string 

the string to be converted. (Input) See Time String below for a description of 
valid string values. 

clock 

the resulting clock value. (Output) Unchanged if an error occurs. 

code 

is a standard status code. (Output) It can have one of the following values: 

error_table_$bad_conversion 

a conversion condition occurred while trying to convert a value. 

error_table_$dt_ambiguous_time 

there is no language common to all words in the time string. 

error_table_$dt_bad_f w 

fiscal_week < 1 or fiscal_week > year_max (which is 52 or 53). 

error_table_$dt_hour_gt_twelve 
the hour given exceeds 12. 

error_table_$dt_multiple_date_spec 

more than one instance of a date has been given. 

error_table_$dt_multiple_diw_spec 

day of the week specified more than once. 

error, table „$dt_multiple_meaning 

the time string does not have the same meaning in all potential languages, 
these being the intersection of all the languages possible for all words 
present. 

error_table_$d t_mul tiple_time_spec 

more than one instance of a time has been given. 

error_table_$dt_multiple_zone_spec 

the zone may only be specified once. 

error_table_$dt_time_conversion_error 
For any of the following reasons: 

a. General syntax error 

b. Month without a day number. 

c. Midnight or noon preceded by an hour other than 12. 

d. Improper use of comma or period. 

e. Improper use of offset 



2-112 



AG93-05 



convert_date_to_binary_ convert_date_to_binary_ 



error_table_$dt_size_error 

the size condition occurred while converting the time string. 

error_table_$too_many_tokens 

the time string contains more tokens than the routine is prepared to handle. 

error_table_$dt_unknown_word 

a word in a time string is not found in the time_info_ token list. 

TIME STRING 

The time string can have up to six parts — adverbial offset, date, time, day of week, 
signed offset, and time zone. Adverbial offsets, if present, must appear leftmost in 
the string. Beyond that, all of the parts are optional and may be in any order. The 
parts may be made up of alphabetic fields, numeric fields, and special characters. 



An alphabetic field is made up of letters and must contain a whole word or an 
abbreviation (usually made up of the first three letters of the word). No distinction is 
made between uppercase and lowercase characters. Although this description gives 
examples in English, each of the words is available in several languages. Any of these 
languages may be used in time strings, but all words within a given string must be in 
the same language. To see the languages defined on your site, type 

d i spl ay_t ime_i nf o -Tang 

A numeric field consists of an optionally signed integer (or fraction) of one or more 
decimal digits. The special characters that may be used in either alphabetic or numeric 
fields are: the slash (/), the period (.), the colon (:), the plus (+), the minus (-), and 
the comma (,). Blanks are not required between alphabetic and numeric fields in the 
time strings; however, they are required between two numeric fields unless the second 
field begins with a plus (+) or minus (-) sign. For example: 

2days^hours lOmi nutes 
\2k$. 17+7hours 
10/17/79Wednesday 

Underscores may be used in place of blanks in the time string. For example: 
09/25/79_l 1 + 1 *2.6_+5_hours 

Usually when a user enters a time string, the time zone is omitted. Although the zone 
is seldom seen, it is very important. The time zone determines the interpretation of 
items given in the time string. Also, the zone is involved in supplying defaults for 
missing items. All defaults are taken from the current absolute time, adjusted by a 
working time zone. If a zone is given in the string, that becomes the working zone. 
Otherwise, the process default time zone is used. 
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This means that whether you convert a string with an explicit zone, such as 
"XXXX_ast" or set the process default to "ast" and then convert the string "XXXX", 
you get the same absolute time. (Note that setting the process default will also 
influence output conversion, while giving an explicit zone does not) To display your 
default zone, type: 

pr i nt_t ime_def aul ts zone 

Multics accepts dates from the year 0001 through 9999. The Julian calendar is used 
for dates from 0001-01-01 through 1582-10-04. The Gregorian calendar is used for 
dates from 1582-10-15 through 9999-12-31. (The dates from October 5, 1582 through 
October 14, 1582 do not exist. They were dropped when the Gregorian calendar was 
adopted. The leap day is always February 29. The lower limit on dates of January 1, 
0001 AD was picked since it begins the era. The upper limit on dates of December 
31, 9999 was chosen to limit year numbers to four digits. The time zones as now 
defined are used regardless of the year. The Multics date/ time system does not 
account for "leap seconds" and, therefore, the difference between any two binary clock 
values that are precisely an integral number of days (hours, minutes, seconds, etc.) 
apart is guaranteed to be evenly divisible by the number of microseconds in a day 



The six parts of the time string are described below. In these descriptions, whenever 
an assumed value is mentioned, it refers to the date/ time adjusted to the working 
zone. 

1. date 

is the day of the year and may be specified only once. Dates may be 
specified using normal date format, calendar date format, day of the week, 
date keywords, fiscal week, request-id, or may be omitted entirely. If no date 
is present, it is assumed to be the next occurrence of the time specified. For 
example, "10A" gives the date on which 10:00 am next occurs. If no date and 
no time are specified, the current date is used. 
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In normal date format, dates are specified as month (or month abbreviation), 
day of month, and year, or as day of month, month, and year. The year is 
optional and, if omitted, is assumed to be the year in which the date will 
occur next That is, if today is March 16, 1978, then March 20 is equivalent 
to March 20, 1978; while March 12 is the same as March 12, 1979. There are 
three forms of normal date, illustrated by the examples below: 

16 March 16 March 1978 

March 16 March 16 1 978 March 16, 1 978 (The comma is optional.) 
3/16 3/16/78 3/16/1978 

Calendar date format permits dates to be specified as a year, month, and day 
of month, separated by minus signs. This is the International Standards 
Organization (ISO) standard format The year is required, and may be given as 
a year of the century. The calendar date format is illustrated by the examples 
below: 

79-12-31 or 1979-12-31 

(represents December 31* 1979) 

The day of the week is a date specifier if present with no other form of 
date. It then selects the first occurrence of the named day AFTER today. 

The date keywords are "yesterday", "today", and "tomorrow". For example, 

6:35A today 
yesterday +120days 

The fiscal week is of the form FWyyyyww. "FW" is the fiscal indicator (in 
English), "yyyy" is the year number, and "ww" is the week number. The fiscal 
week begins on Monday and ends on Sunday. This form converts to the date 
of the Monday, but another day within the week may be selected by adding a 
day name. For example, "FW198413 m" gives "03/26/84 0000. Mon", while 
"FW198413 m Wed" gives "03/28/84 0000. Wed". The fiscal indicator may be 
separated from the number but the ordering must remain, i.e. "FW185425" or 
"FW 185425" but not "185425 FW". 

A request-id is a 19-character string used by several programs in the system, 
such as list_output_request. It contains a complete date from year, in century 
down thru microseconds in this form: 

yymmdd.HHMMSS.SSSSSS 

If no zone is specified, it is interpreted in GMT, not the process default. A 
request-id specifies a time as well as a date, so no other time specification 
may be given. 
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2. day of week 

is the day of the week (e.g., Monday) and may be present only once. When 
the day of the week is present along with one of the other forms of date 
specification, that date must fall on the indicated day of the week. 

3. time 

is the time of day and may only be present once. If omitted, it is assumed to 
be the current time. Time may be given as 24-hour format, 12-hour format, 
or the time keyword "now". The 24-hour time format consists of a four-digit 
number followed by a period, (hhmm., where hh represents hours, and mm 
represents minutes). This number may be followed by an optional decimal 
fraction-of-a-minute field (e.g., hhmm.m). Also acceptable are hours and 
minutes fields separated by colons (hh:mm). This may be optionally followed 
by either a fraction-of-a-minute field (hh:mm.m), or a seconds field (hh:mm:ss). 
The seconds, in turn, may be include a fraction-of -second field (e.g., 
hh:mm:ss.s). Examples of 24-hour time are: 

1545-715 

15:45.715 

15:45:42 

15:45:42.08 

The 12-hour time format must end with a meridiem designator (i.e., A, P, am, 
pm, noon, (or n), midnight (or m)). Midnight and noon can be indicated by 
simply giving the meridiem designator. The designator may be preceded by 
time expressed as hours, hours: minutes, or hours:minutes:seconds (including an 
optional fraction of a second or fraction of a minute, as mentioned above). 
Examples of 12-hour time are: 

midnight 
5 am 
5:45A 

3:59:59.000001pm 
11:07:30.5pm 
12 n 

There is a set of illegal times, 24:00-24:59, which are handled anyway. These 
are taken to mean 0:00-0:59 of the following day. Note that midnight is the 
beginning of a day (00:00) not the end. 
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4. signed offset 

is an adjustment to be made to the clock value specified by the other fields. 

Offsets may be specified in any and all of the following units (i.e. singular, 
plural, or abbreviation): 



year 


years 


yr 


month 


months 


mo 


week 


weeks 


wk 


day 


days 


da 


hour 


hours 


hr 


mi nute 


mi nutes 


mi n 


second 


seconds 


sec 



microsecond microseconds usee 



Each unit may be present one or more times, each preceded by an optionally 
signed fixed point number. If offset fields are the only thing present, the 
offsets are added to the default values of date and time, as described above. 

If the month offset results in a nonexistent date (e.g., "Jan 31 3 months" 

would yield April 31), the last date of the resulting month is used (e.g., April 
30). 

Examples of offset fields are: 

3 weeks -60 hours 

(60 hours before 3 weeks after now) 
1.5 hr 5mi n 

(an hour and 35 minutes from now) 
1 hour 5 minutes 

(an hour and five minutes from now) 

The order in which offset values are applied to the clock value can affect the 
resultant clock value. Offset values are applied in the following order: 

year, month, week, day, hour, 
minute, second, microsecond 

Assuming that today is September 25, 1979, then: 
10/1 -1 day +1 month 

results in a clock value for 10/31/79, rather than for 10/30/79. 

"Monday 6 am 2 weeks" means "two weeks after the next occurrence of 
Monday, at 6:00 am on that day". 
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NOTE: There is also a non-offset use of these words, available in combination with 
the word "this", i.e. "this month". Some of these combinations can be used in 
building date and time parts. For example, "this_month_l,_this_year" or 
"this_hour:23" is valid, while just "this_day" is not The exact form of this 
combination will vary according to language. In some languages, the word for 
"this" changes according to which unit it is applied to. In other languages, 
there may be a single word which does the job. To list the word used as 
"this" for each unit, type: 



is a before/ after kind of adjustment and may be used any number of times. 
This offset is recognized by the presence of "before", "on", or "after" in the 
time string. If present, adverbial offsets must appear first. These are the 
forms available: 

DAY-NAME before 

r> * v/ 11 « ur u 

DAY-NAME before or on 
DAY-NAME after 
DAY-NAME on or after 
DAY-NAME after or on 
SIGNED-OFFSETs before 
SIGNED-OFFSETs after 

When adverbial offsets are present, they partition a string into a series of 
adjustments followed by a base time. These sections are processed in a right to 
left manner. Referring to the first example below s there are 3 sections. First 
"6:00 am 400sec" is handled, supplying all necessary defaults and making the 
ordinary (400sec) offset adjustment. Then "Monday after" is applied to give a 
new value. And finally "2 wk -5min after" is applied to this new value to 
give the final value. 

2 wk ~5min after Monday after 6:00 am 400sec 

20 minutes before now 

2 days after today 

2500 weeks after 1776-7-** 

Tue after Mon on or after 11/1 

This last item describes election day in the USA, i.e. the first Tuesday after 
the first Monday in November. 



di spl ay_t ime_i nfo_$of f set -language LANGUAGE_NM 



5. 



adverbial offset 
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6. zone 

is the time zone to be used in making the conversion to Greenwich mean 
time, which is the internal form of all clock readings. It may be either a 
zone differential, or any of the zone abbreviations known at the site. A zone 
differential is a 5-character string, "sHHMM" ("s" is a sign, "HH" is a 2-digit 
hour, and "MM" is a 2-digit minute). This may only be used immediately 
following a time specification. "12:15-0330" says that 12:15 is the local time 
and -0330 specifies that the local time was generated by subtracting 3.5 hours 
from GMT. To list the zone abbreviations known at a site, type: 

di spl ay_t ime_i nf o -zones 

If any defaults are needed, the current instant in time is broken down into 
years, months, days, etc. with respect to a "working zone". This working zone 
can make a great deal of difference, because, for example, at a given instant it 
can be Tuesday in New York and Wednesday in Bankok, or it can be 22:07 in 
London and 3:37 in Singapore. Thus, the zone is as important in applying 
defaults to week days and years as it is to hours and minutes. 

Many of the date/ time commands allow a "-zone X" argument to specified. In 
this case, X may be any of the zones known at the site. It may NOT be a 
time differential. 



Entry: convert date to binary Srelative 

This entry point is similar to the convert_date_to_binary_ entry point, except that the 
clock reading returned is computed relative to an input clock time rather than the 
current clock time. Thus the clock reading returned for the string "March 26" is the 
clock reading for the first March 26 following the input clock time, rather than the 
clock reading for the first March 26 following the current clock time. Given a 72-bit 
clock time to use, this entry point converts a character representation of a date and 
time to the equivalent 72-bit clock reading. 

USAGE 

declare convert_date_to_binary_$re1ative entry (char (*) , fixed bin (71), 
fixed bin(7D, fixed bin(35)); 

call convert_date_to_binary_$relative (string, clock, clock_in, code) 

ARGUMENTS 

string 

is the character representation of the clock reading desired. (Input) 
clock 

is the computed clock value relative to the clock_in argument. (Output) 
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clock_in 

is the clock time used to compute the clock value. (Input) 

code 

is a standard status code. (Output) 



Name: convert dial message 

The convert_dial_message_ subroutine is used in conjunction with the dial_manager_ 
subroutine to control dialed terminals. It converts an event message received from the 
answering service over a dial control event channel into status information more easily 
used by the user. 



Entry: convert dial message Sreturn io module 

This entry point is used to process event messages from the answering service 
regarding the status of a dialed terminal or an auto call line. In addition to returning 
line status, this entry point also returns the device name and I/O module name for 
use in attaching the line through the iox_ subroutine. See the MPM Subroutines for 
further description of the iox_ subroutine. 

USAGE 

declare convert_dial_message_$return_io_module entry (fixed b i n (7 1 ) > 
char (*) , char (*) , fixed bin, 1 aligned, 2 bit(l) unal, 2 bit(l) 
unal, 2 bit(l) unal. 2 bit (33) unal, fixed bin (35)); 

call converted i a l_message_$return_io_module (message, channel_name, 
io_module, n_dialed, flags, code); 

ARGUMENTS 

message 

is the event message to be decoded. (Input) 
channel_name 

is the name of the channel that has dialed up or hung up. (Output) 
io_module 

is the name of the iox_ I/O module to be used with the assigned device. 
(Output) 

n_diaied 

is the number of terminals currently dialed to the process or -1. (Output) 
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flags 

is a bit string of the following structure: (Output) 

del 1 flags al igned, 

2 dialed_up bit(l) unal, 

2 hung_up bit ( 1 ) unal, 

2 control bit ( 1 ) unal, 

2 pad bit (33) unal ; 

Only the first three bits have meaning, and only one can be on at a time. See 
"Notes" below for complete details. 

code 

is a standard status code. (Output) See "Notes" below. 
NOTES 

The message may be either a control message or an informative message. Informative 
messages have flags. control off ("0"b), n_dialed is set to -1, channel is set to the 
name of the channel involved, io_module is set to the name of an I/O module, and 
either flags. dialed_up or flags.hung_up is on, indicating that the named channel has 
either just dialed up or just hung up. The io_module name is provided as a 
convenience; the caller is not required to use the name returned by this subroutine. 

Control messages have flagsxontrol on OT'b), and n_dialed is set to the number of 
dialed terminals or -1. The code is either 0 (request accepted) or one of the 
following values: 

error_table_$action_not_perf ormed 

the requested action was not performed; typically, this indicates an attempt to 
manipulate a channel that the requesting process can not control. 

error_table_$ai_out_range 

access to the requested channel is prohibited by AIM. 

error_table_$bad_name 

the channel_name does not conform to required syntax. 

error_table_$badcall 

the dial message was -1. The dial_manager_ subroutine will set 
dial_manager_arg.dial_message to -1 when an error occurs and there is no 
answering service diai_message to return. 

error_table_$bigarg 

the dial_out_destination is too long. 

error_table_$dial_active 

the process is already serving a dial qualifier. 
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error_table_$dial_id_busy 

the dial_qualifier is already being used by another process. 

error_table_$insuf f icient_access 

the running process does not have the access permission required to perform the 
requested operation. 

error_table_$invalid_resource_state 

the channel is not configured to allow the requested operation. 

error_table_$name_not_f ound 

the dial_qualifier is not registered. 

error_table_$no_connection 

it was not possible to complete the connection, e.g., dial-out failure. 

error_table_$no_dialok 

the requesting process does not have the dialok attribute. 

error_tabie_$order_error 

an error occurred while processing an order on this channel. 

error_table_$request_not_recognized 
indicates a software error. 

error_table_$resource_not_f ree 

the requested channel is already in use. 

error_table_$resource_unavailable 

no channel could be found that satisfied required characteristics. 

error_table_$resource_unknown 

the channel specified does not exist. 

error_table_$unable_to_check_access 

typically indicates that the process does not have required access, but may indicate 
an administrative error. 

error_table_$unimplemented_version 

the version of the dial_manager_arg structure supplied is not supported by 
dial_manager_. This error code may also indicate an internal software error. 



Name: convert status code 

The convert_status_code_ subroutine returns the short and long status messages from 
the standard status table containing the given status code. Status codes are described in 
the Programmer's Reference Manual. 
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USAGE 

declare convert_status_code_ entry (fixed bin(35)» char (8) aligned, 
char (100) al i gned) ; 

call convert_status_code_ (code, shortinfo, longinfo); 

ARGUMENTS 

code 

is a standard status code. (Input) 
shortinfo 

is a short status message corresponding to code. (Output) 
longinfo 

is a long status message corresponding to code; the message is padded on the 
right with blanks. (Output) 

NOTES 

If code does not correspond to a valid status code, shortinfo is "XXXXXXXX", and 
longinfo is "Code ddd", where ddd is the decimal representation of code. 



Name: copy 

This subroutine produces a copy of a Multics non-directory branch. Name duplication 
is handled by nd_handler_. 

USAGE 

del copy_ external entry (ptr) ; call 

copy_ (copy_opt ions_ptr) ; 

ARGUMENTS 

copy_options_ptr 

is the pointer to copy_options structure (Input) 

NOTES 

All errors are handled via sub_err_. An attempt to copy a segment into itself is 
refused. 
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STRUCTURE 



The copy_options structure is defined as follows: 



1 copy_options 



2 version 
2 cal ler_name 
2 source_dir 
2 source_name 
2 target_dir 
2 target_name 
2 flags, 



aligned based (copy_options_ptr) , 
char (8) , 



char (32) unal, 

char (168) unal , 

char (32) unal , 

char (1 68) unal , 

char (32) unal, 



3 mbz 
2 copy_i terns 



3 no_name_dup 
3 raw 
3 force 
3 delete 

3 target_err_swi tch 



b 
b 
b 
b 
b 
b 



t (1) unal i gned, 

t (1) unal i gned, 

t (1) unal i gned, 

t (1) unal igned, 

t (1) unal i gned, 

t (31) unal i gned, 
ke copy_flags; 



STRUCTURE ELEMENTS 
version 

is the current version of this structure and has the value of the named constant 
COPY_OPTIONS_VERSION_l. 

caller_name 

is the name of the program calling copy_, required when querying the user about 
duplicate names. See no_name_dup below. 



is the absolute pathname of the directory containing the entry to be copied. 

source_name 

is the name of the entry to be copied. 

target_dir 

is the absolute pathname of the directory into which a copy of the entry is to be 
placed. 

target_name 

is the name of the entry created to hold the copy of the original entry. 
no_name_dup 

is set to "0"b if the user is to be queried in case of a duplication of the 
target_name and "l"b if there is to be no query, in which case sub_err_ is 
signalled. 



source_dir 
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raw 

is set to "0"b if copy_ is to honor the extended type of the entry, and "l"b if it 
is to regard it as a standard type entry. 

force 

is set to "l"b if access to the target is to be forced, 
delete 

is set to 'Tb if the original is to be deleted after it is copied. 

target_err_switch 

is set if an error occurred referencing the target. 

mbz 

is reserved for future use and must be set to zero. 
copy_items 

is structured like the copy_flags structure, which is defined in the include file 
copy_flags.incl.pll. The structure is defined as follows: 

1 copy_flags aligned based, 

2 names bit (1) unaligned, 

2 acl bit (1) unaligned, 

2 r i ng_brackets bit (1) unaligned, 

2 max_length bit (1) unaligned, 

2 copy_switch bit (1) unaligned, 

2 saf ety_swi tch bit (1) unaligned, 

2 dumper switches bit (1) unal igned, 

2 entry_bound bit (1) unaligned,. 

2 extend bit (1) unaligned, 

2 update bit (1) unaligned, 

2 mbz bit (26) unaligned; 

When variables in the copy_flags structure have a value of "l"b, the 
designated attribute are copied to the new entry (as long as the attribute is 
supported for the type of entry). In the case of extend, the contents of the 
original entry may be appended to the end of the target entry. In the case 
of update, the contents of the original entry may replace the contents of the 
target entry. 



2-125 



AG93-05 



copy_acl_ 



copy_acl_ 



Name: copy acl 

The copy_acl_ subroutine copies the access control list (ACL) from one file, segment, 
multisegment file, or directory to another, replacing the current ACL if necessary. 

USAGE 

declare copy_acl_ entry (char (*) , char (*) , char (*) , char (*) , bit(l) 
aligned, fixed bin (35)); 

call copy_acl_ (source_dir, source_ent, target_dir, target_ent, 
target_error_sw, code) ; 

ARGUMENTS 

source_dir 

is the pathname of the directory containing the source file or source directory 
whose ACL is to be copied. (Input) 

source_ent 

is the en try name of the source file or source directory. (Input) 
target_dir 

is the pathname of the directory containing the target file or target . directory 
whose ACL is replaced. (Input) 

target_ent 

is the entryname of the target file or target directory. (Input) 
target_error_sw 

is "0"b if the siatus code reflects an error in listing the ACL of the source file 
or directory, and is 'T'b if the code reflects an error in replacing the ACL of 
the target file or directory. (Output) 

code 

is a standard status code. (Output) 
NOTES 

An attempt to copy the ACL from a source file to a target directory, or from a 
source directory to a target file causes an error. Source and target must both be a 
file, or both a directory. 

Links are chased in the processing of the source and target pathnames. 
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Name: copy_dir_ 

Copies a subtree from one point in the hierarchy to another, and optionally deletes 
the source subtree. 

USAGE 

del copy_di r_ entry (char (*) , char (*) , char (*) , char (*) , ptr, fixed 
bin (35)); 

call copy_dir_ (caller, source_dir, source_ename, target_dir, 
target_ename, pcopy_d i r_opt i ons , code); 

ARGUMENTS 

caller 

is the name of the calling procedure. (Input) 
source_dir 

is the pathname of the source directory. (Input) 

source_ename 

is the source entry name. (Input) 

target_dir 

is the pathname of the target directory. (Input) 

target_ename 

is the target entry name. (Input) 

pcopy_dir_options 

is a pointer to the copy_dir_options structure shown below under "Info Structure". 
(Input) 

code 

is a standard system status code. (Output) 
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INFO STRUCTURE 

The following structure is declared in copy_dir_options.incl.pll: 
del 1 copy_di r_opt ions aligned based (pcopy_d i r_opt i ons) , 



vers i on 


fixed bin, 


entry control 


al i gned, 


3 1 ink 


bit (1) 


unal , 


3 seg 


bit (1) 


unal , 


3 dir 


bi t(l) 


una 1 , 


3 msf 


bit (1) 


una 1 , 


3 nnlk 


bit (1) 


unal , 


3 padl 


bit (3D 


unal , 


opera t ion_control 


al i gned, 


3 delete 


bit (1) 


unal , 


3 brief 


bit (1) 


unal , 


3 force 


bit (1) 


unal , 


3 replace 


bit (1) 


unal , 


3 update 


bit (1) 


unal , 


3 ac i 


bi t ( 1) 


una? , 


3 primary 


bit (1) 


unal , 


3 1 i nk_trans 1 at i on 


bit (1) 


unal , 


3 chase 


bit (1) 


una 1 , 


3 parent ac sw 


bit (1) 


unal , 


3 pad2 


bit (26) 


unal ; 



del copy_di r_opt ions_vers ion_0 fixed bin init(O) int static opt i ons (constant) ; 
del pcopy_d i r_opt i ons ptr; 

STRUCWRE ELEMENTS 

version 

is the version number of this structure, currently copy_dir_options_version_0. 

link 

if set to "l"b then links are copied. 

seg 

if set to "l"b then segments are copied. 

dir 

if set to "l"b then inferior directories are copied. If this is not set then the 
subtree is not walked. 

msf 

if set to "l"b then multisegment-files are copied. 

nnlk 

if set to "l"b then non-null links are copied. 
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padl 

is unused and must be zero, 
delete 

if set to "l"b then the source_dir is deleted after the copying is complete, 
brief 

if set to 'T'b suppresses the printing of warning messages such as "Bit count is 
inconsistent with current length" and "Current length is not the same as records 
used". 

force 

if set to 'T'b executes, when target_dir already exists, without asking the user. If 
force is not set, the user is queried. 

replace 

if set to "l"b deletes the existing contents of target_dir before the copying begins. 
If target_dir is non-existent or empty, this control argument has no effect. The 
default is to append the contents of source_dir to the existing contents of 
target_dir. Setting of replace conflicts with the setting of update, and 
error_table_$inconsistent is returned. 

update 

if set to "l"b causes copying of only those entries in source_dir that have 
comparable entries in target_dir. Setting of update conflicts with the setting of 
replace, and error_table_$inconsistent is returned. 

acl 

if set to 'T'b gives the ACL on the source_dir entry to its copy in target_dir. 
Although initial ACLs are still copied, they are not used in setting the ACL of 
the new entries when not set. 

primary 

if set to 'T'b only primary names are copied. If not set, all the names of the 
selected entries are copied. 

link_translation 

if set to 'T'b then links will be translated. If there are references to the source 
directory in the link pathname of a link being copied, the link pathname is 
changed to refer to the target directory. 

chase 

if set to 'T'b copies the target of a link. Chasing links eliminates link 
translation. 
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parent_ac_sw 

if set to "l"b when target directories need creating. The access class of the 
target_dir is obtained from the target's parent directory. Otherwise, the access 
class is determined from the source_dir. This switch may be used by privileged 
applications to make a downgraded copy of an upgraded hierarchy. The caller 
must have previously set the seg and dir AIM privileges in order to read the 
contents to the upgraded hierarchy. 

pad2 

is unused and must be zero. 
ACCESS REQUIRED 

Status permission is required for source_dir and all of the directories in its tree. 
Status permission is required for the directory containing source_dir. Read access is 
required on all files under source_dir. Append and modify permission are required for 
the directory containing target_dir if target_dir does not exist Modify and append 
permission are required on target_dir if it already exists. 

If acl is not specified, the system default ACLs are added, then the initial ACL for 
the containing directory is applied (which may change the system supplied ACL). 
Initial ACLs are always copied for the current ring of execution. 

NOTES 

If target_dir already exists and force is not specified, the user is so informed and 
asked if processing should continue. If target_dir is contained in source_dir, an 
appropriate error message is printed and the subroutine returns. 

If name duplication occurs while appending the souree_dir to the target_dir and the 
name duplication is between directories; the user is queried whether processing should 
continue. If the user answers yes, the contents of the directory are copied (appended) 
but none of the attributes of that directory are copied. If the answer is no, the 
directory and its subtree is skipped. If name duplication should occur between 
segments, the user is asked whether to delete the existing one in target_dir. 

If replace is specified or target_dir does not exist, name duplication does not occur. 

If part of the tree is not copied (by specifying a storage system entry key), problems 
with link translation may occur. If the link target in the source_dir tree was in the 
part of the tree not copied, there may be no corresponding entry in the target_dir 
tree. Hence, translation of the link causes the link to become null. 
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create_data_segment_ 



Name: cpu time and paging 

The cpu_time_and_paging_ subroutine returns the virtual CPU time used by the calling 
process since it was created as well as a measure of the paging activity of the process. 

USAGE 

declare cpu_t ime_and_pagi ng_ entry (fixed bin, fixed bin (71), fixed 
bin) ; 

call cpu_t ime_and_pag i ng_ (pf, time, pd_faults); 

ARGUMENTS 

Pf 

is the total number of page faults taken by the calling process. (Output) 

time 

is the virtual CPU time (in microseconds) used by the calling process. (Output) 
pd_faults 

was previously the total number of page faults from the paging device for the 
calling process. This value is always returned as zero. (Output) 



Name: create data segment 

The create_data_segment_ subroutine is used in conjunction with the create_data_segment 
command to create a standard object segment from PL/I data structures passed to it 
as parameters. The create_data_segment_ subroutine is called from a PL/I program 
that has defined in it either one or two specific PL/I structures, whose contents are 
to be placed in the text and /or static sections of the object segment to be created. 
The level-2 structure component names become entry point names for the object 
segment, i.e., names that can be found by links so that other programs may reference 
the data by name. 

USAGE 

declare create_data_segment_ entry (ptr, fixed bin (35)); 
call create_data_segment_ (cds_arg_ptr , code); 
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ARGUMENTS 



cds_arg_ptr 

is a pointer to a structure (see "Structure" below) containing information to be 
passed to the create_data_segment_ subroutine, specifying the structures to be used 
to create the object segment. (Input) 

code 

is a standard status code. (Output) It can be error_table_$translation_f ailed if no 
object segment is created. 



STRUCTURE 



The structure that passes information to the create_data_segment_ subroutine can be 
found in the library include file cds_args.incl.pll. It is declared as follows: 



del 1 cds_args 

2 sections (2) , 

3 P 
3 len 

3 struct_name 

2 seg_name 

2 num_exc 1 ude_names 

2 exc 1 ude_array_ptr 

2 switches, 

3 def s_i n_l i nk 
3 separate_stat i c 
3 have_text 
3 have_static 
3 pad 



based al i gned, 
ptr, 

fixed bin (18) , 
character (32) , 
character (32) , 
fixed bin, 
ptr, 

bi t (1) unal , 
bit ( 1 ) unal , 
b i t (1) unal , 
b i t (1) unal , 
bit (32) unal; 



STRUCTURE ELEMENTS 



sections 

describe the PL/ 1 structures in the calling program that are used to define the 
text and static sections of the object segment; section (1) describes the structure 
to be used for the text section, (if cds_args.switches.have_text is on), and section 
(2) describes the structure to be used for the static section (if 
cds_args.switches.have_static is on). 



is a pointer to a region of data, described by the appropriate structure, whose 
contents are to be copied into the appropriate section of the object segment. 

len 

is the length, in words, of the region pointed to by p. It must be the same as 
the word size of the appropriate structure. 
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struct_name 

is the level-1 name of the structure in the calling process that is used to define 
the entry point (segdef) names of the corresponding section of the object segment. 

The structure must be known throughout the PL/ 1 language scoping rules to the 
block that contains the call to create_data_segment_. 

This structure must not be an array at its outermost level. It can be of any 
storage class and can contain arbitrary "like" attributes. 

All level-2 names in this structure will become entry point (segdef) names in the 
corresponding section of the object segment, unless excluded by the exclude array 
(see below). The location of the entry point (segdef) will be at an offset in the 
corresponding section of the object segment equal to the offset of the given 
component in the supplied structure. Hence, only a name defining a field that 
begins on a word boundary may be validly used. 

seg_name 

is the entryname of the object segment to be created in the working directory. 
The seg_name must be the same as the entry name of their source segment | 
without the suffix ".cds". | 

num_exclude_names . 

is the number of names in the exclude array. It should be 0 if there is no 
exclude array. (See below.) 

exclude„array_ptr 

is a pointer to the exclude array, if one is provided. It may be null. 

The exclude array is an array of character(32) star names (see the match_star_names_ 
subroutine) that select those level-2 names in the supplied structures that should 
not be made into entry point names. For instance, the names "pad*" and "mbz*" 
would eliminate all names beginning with either mbz or pad. 

If no exclude array is supplied, all level-2 names are made into entry point 
names. 

switches 

control the options of the create_data_segment_ subroutine. 

defs_in_link 

controls placement of the definition section. 

"l"b places definition section of the object segment in its linkage section; this 

option creates a nonstandard object segment, and should not be used. 
"0"b places definitions contiguous to the text section. 
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separate_static 

controls whether the object segment has a separate static section. 

'T'b separate static section 

"0"b static resides in the linkage section 

have_text 

indicates whether or not there is a text section. 

'T'b cds_args.sections(l) describes a structure to be used for defining the text 

section of the object segment 
"0"b there is no text section (zero length) 

have_static 

indicates whether or not there is a static section. 

'T'b cds_args.sections(2) describes a structure to be used for defining the static 

section of the object segment 
"0"b there is no static section (zero length) 

pad 

is reserved, and must be all zeros. 
NOTES 

The brief translator name placed in object segments produced by the create_data_segment_ 
subroutine is cds. 

If the defs_in_link switch is supplied as on ('T'b), then a nonrelocatable, nonstandard 
object segment is produced. 

All text and static-resident information created is supplied with absolute relocation. 
Hence, one must be wary of threads and pointers in one's structures, as they are not 
relocated if the object segment is bound. 

The program that calls the create_data_segment_ subroutine must be in the PL/ 1 
language. It must be compiled with the -table control argument The create_data_segment 
command provides for this. 

It is essential that structures specified by cds_args. sections be at least referenced in the 
calling program, or they are not described in the runtime symbol table. 

The create_data_segment_ program, in its capacity as a translator, issues diagnostic 
messages on the terminal, as opposed to returning detailed status codes. 

All regions of the text and /or static sections not explicitly set by the calling program, 
whether via "init" attributes or explicit code, may not be assumed to contain zero or 
any other quantity. 
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Name: create ips mask 

The create_ips_mask_ subroutine returns a bit string that can be used to disable 
specified ips (interprocess signal) interrupts (also known as ips signals). 

USAGE 

declare create_i ps_mask_ entry (ptr, fixed bin, bit (36) aligned); 

call create_i ps_mask_ (array_ptr, lng, mask); 

ARGUMENTS 

array_ptr 

is a pointer to an array of ips names that are declared as char(32) aligned. 
(Input) 

lng 

is the number of elements in the array pointed to by array_ptr. (Input) 
mask 

is a mask that disables all of the ips signals named in the array. (See "Notes" 
below.) 

NOTES 

If any of the names are not valid ips signal names, the condition create_ips_mask_err 
is signalled. Currently, the allowed ips names are: 

quit 

cput 

alrm 

neti 

sus_ 

trm_ 

wkp_ 

Pgt_ 

system_shutdown_scheduled_ 
dm_shutdown_scheduled_ 

If the first name in the array is -all, then a mask is returned that masks all 
interrupts. 

The returned mask contains a "0"b in the bit position corresponding to each ips name 
in the array and a "l"b in all other bit positions. The bit positions are ordered as in 
the above list. It should be noted that it is necessary to complement this mask (using 
a statement of the form "mask - A mask") in cases where the requirement is for a 
mask with "1" bits corresponding to specified interrupts. An ips mask is used as an 
argument to the hcs_$reset_ips_mask and hcs_$set_ips_mask entry points. 
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Name: cross ring_io. 



Entry: cross_ring__io__$allow_cross 

The cross_ring_io_$allow_cross entry point must be called to allow use of an I/O 
switch via cross-ring attachments from an outer ring. The call must be made in the 
inner ring before the outer ring attempts to attach. 

USAGE 

declare cross_r i ng_io_$al low_cross entry (char (*) , fixed bin, 
fixed bin (35)) ; 

call cross_r i ng_i o_$al 1 ow_cross (swi tch_name, ring, code); 

ARGUMENTS 

switch_name 

is the inner ring switch name. (Input) 

ring 

is the highest validation level from which switch_name may be used. (Input) 

code 

is a standard status code. (Output) 
NOTES 

This entry may be called more than once with the same switch_name argument. 
Subsequent calls are ignored. 



Name: cu 

The cu_ subroutine contains a number of useful command utility programs that 
provide functions not directly available in the PL/ 1 language. Although the various 
cu_ entry points are designed primarily for the use of command writers, many may 
prove useful to Multics users and subsystem developers. The entry points can be 
divided into four functional categories: argument processing, ready states, stack utility, 
and miscellaneous. 
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The following is a list of all the entry points in the cu_ subroutine, divided into the 
four categories. A brief explanation of each category follows the list. The entry 
points themselves are then described, in alphabetical order. 



Argument Processing 


Stack Utility 


cu_$af_arg_count 


cu_$grow_stack_f rame 


cu_3>ai _arg_count_rei 


cu_3>snrinK_stacK_i rame 


cu_$af_arg_ptr 


cu_$stack_f rame_ptr 


cu_$af_arg_ptr_rel 


cu_$stack_f rame_size 


cu_$af_return_arg 




cu_$af_return_arg_rel 


Active String Evaluation 


cu_$arg_count 




cu_$arg_count_rel 


cu_$evaluate_active_string 


/»n Corn liel" t^Tt* 

cu_ Jargons i_p ir 


cu_4>gei_cvaiuaie_ac u ve_s inng 


cu_$ar&_ptr 


cu_$reset_evaluate_active_string 


cu_$arg_ptr_rel 


cu_$set_evaluate_active_string 


cu_$generate_call 




Ready States 


Command Error Handlers 


cu_$get_ready_mode 


cu_$cl 


cu_$get_ready_procedure 


cu_$get_cl_intermediary 


cu_$ready_proc 


cu_$reset_cl_intermediary 


cu_$reset_ready_procedure 


cu_$set_cl_intermediary 


cu_$set_ready_mode 




cu_$set_ready_procedure 


Ring Validation Level 


Command Processor Escape 


cu_$level_get 




cu_$level_set 


cu_$cp 




cu_$get_command_name 


Miscellaneous 


cu_$get_command_name_rel 




cu_$get_command_processor 


cu_$caller_ptr 


cu_$reset_command_processor 


cu_$decode_entry_value 


cu_$set_command_processor 


cu_$make_entry_value 



AIDS IN ARGUMENT PROCESSING 

These entry points are designed to be used by such programs as commands and active 
functions, which in turn may be invoked with a variable number of arguments. The 
entry points are tools to be used in obtaining the number of arguments, or a pointer 
to an argument or argument list, or to reference the return argument of an active 
function. Knowledge of the details of implementation is not necessary. 

READY STATES 

These entry points enable the user to invoke a ready procedure, to determine the state 
of a ready procedure or ready mode, or, if need be, to change it. 
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STACK UTILITY 



These entry points enable the user to perform operations on his stack frame; in 
general, they are for advanced applications. 



ACTIVE STRING EVALUATION 



These entry points enable the user to evalueate active strings within a closed subsystem 
environment which are a sequence of one or more active function invocations with 
their arguments. 



COMMAND ERROR HANDLERS 



These entry points enable the user to handle any error conditions that can be signalled 
within a closed subsystem environment by passing control to the procedure entry point 
currently defined as the standard error handler. A diagnostic message is printed and a 
procedure is called to reenter command level. 



COMMAND PROCESSOR ESCAPE 



These entry points permit the user to escape from the closed subsystem environment 

IV VAWUIW UU1V1 WV/ililliailW-O UJ £S<UK»lll£ tilV VAVVUIW XV^UWOl LU U.1V VU11V11L 

entry point defined as the command processor. 



RING VALIDATION LEVEL 



These entry points enable the user to change the current protection ring validation 
level for procedures that must distinguish the periods of time when it is acting in 
behalf of itself (i.e., in its own ring) and when it is acting in behalf of another 
procedure that can be in an outer (i.e., less privileged) protection ring. 



MISCELLANEOUS 



These entry points enable the user to perform a variety of tasks that do not fit any 
of the above categories. 



Entry: cu $af arg count 

This entry point should be called by an active function. It returns to its caller the 
number of arguments passed to the caller by its caller, not including the active 
function return argument. If the caller has not been invoked as an active function, a 
standard status code is returned, and, if the code is error_table_$not_act_fnc, nargs is 
the number of arguments in the call (similar to the cu_$arg_count entry point 
described below). 
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USAGE 

declare cu_$af_arg_count entry (fixed bin, fixed bin (35)); 

call cu_$af_arg_count (nargs, code); 

ARGUMENTS 

nargs 

is the number of input arguments passed to the caller. (Output) 

code 

is a standard status code. (Output) 
error_table_$nodescr 

no argument descriptors were passed to the caller or an incorrect argument 

list header was encountered. 
error_table_$not_act_f nc 

the caller was not invoked as an active function. 

NOTES 

This entry point and the five following entry points beginning with $af_ have been 
provided so that active functions need not have knowledge of the mechanism for 
returning arguments. 

The entry points cu_$af_arg_count and cu_$af_arg_count_rel are retained for historical 
reasons; active f unction procedures should call cu_$af _return_arg and cu_$af _return_arg_rel 
instead to obtain the location and maximum length of the return argument as well as 
the arg_count. This information will be needed for the active function to return a 
value. When the procedure is invoked as an active function, the value of arg_count 
returned by cu_$af_arg_count will be one less than the value returned by cu_$arg_count, 
otherwise they will be the same. 



Entry: cu $af arg count rel 

This entry point is similar to cu_$af_arg_count, but instead of looking in the 
argument list of its caller, it is given a pointer to the argument list. 

USAGE 

declare cu_$af_arg_count__re 1 entry (fixed bin, ptr, fixed bi n (35) ) 5 
call cu_$af_arg_count_rel (nargs, arg_l i st_ptr , code); 
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ARGUMENTS 
nargs 

is the number of input arguments passed to the caller. (Output) 

arg_list_ptr 

is a pointer to an argument list. (Input) 

code 

is a standard status code. (Output) 
error_table_$nodescr 

no argument descriptors were passed to the caller or an incorrect argument 

list header was encountered 
error_table_$not_act_f nc 

the caller was not invoked as an active function 



Entry: cu_$af__arg ptr 

This entry point assumes it has been called by an active function. It operates in the 
same fashion as cu_$arg_ptr (described below), except that it verifies that the caller 
was invoked as an active function, and does not allow the return argument to be 
accessed. If the (i+l)st argument does not exist, the code error_table_$noarg is 
returned. The return argument is always the last one; thus, use of this entry point 
and cu_$af_return_arg allows the active function to be independent of the position of 
the return argument in the argument list (see "Notes" under cu_$af_arg_count above). 

USAGE 

declare cu_$af_arg_ptr entry (fixed bin, ptr, fixed b?n(21)» 
fixed bin (35)) ; 

call cu_$af_arg_ptr (arg_no, arg_ptr, arg_len, code); 

ARGUMENTS 

arg_no 

is the number of the desired argument. (Input) 
arg_ptr 

is a pointer to the unaligned character-string argument specified by arg_no. 

(Output) It is set to the null value if any error is encountered. 

arg_len 

is the length (in characters) of the argument specified by arg_no. (Output) It is 
set to 0 if any error is encountered. 
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code 

is a standard status code. (Output) 
error_table_$nodescr 

the argument list does not contain descriptors. In this case, argjen is set j 
to zero. I 

error_table_$not_act_f nc 

the caller was not invoked as an active function. 

error_table_$noarg 

the program does not have an arg_no'th argument. In this case, arg_ptr is | 
set to null and argjen is set to zero. i 



Entry: cu__$af arg__ptr rel 

This entry point is similar to cu_$af_arg_ptr but instead of looking in the argument 
list of its caller, it is given a pointer to the argument list. 

USAGE 

declare cu_$af_arg_ptr_rel entry (fixed bin, ptr, fixed bin(21), 
f i xed bin (35) , ptr) ; 

call cu_$af_arg_ptr_rel (arg_no, arg_ptr , arg_len, code, arg_l i st_ptr) ; 

ARGUMENTS 

arg_no 

is the number of the desired argument (Input) 
arg_ptr 

is a pointer to the unaligned character-string argument specified by arg_no. 
(Output) It is set to the null value if any error is encountered. 

arg_len 

is the length (in characters) of the argument specified by arg_no. (Output) It is 
set to 0 if any error is encountered. 

arg_list_ptr 

is a pointer to an argument list. (Input) 

code 

is a standard status code. (Output) 
error_table_$nodescr 

the argument list does not contain descriptors. In this case, arg_len is set 

to zero. 
error_table_$not_act_f nc 

the caller was not invoked as an active function. 
error_table_$noarg 

the program does not have an arg_no'th argument. In this case, arg_ptr is 
set to null and arg_len is set to zero. 
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Entry: cu m $af__return_arg 

This entry point assumes it has been called by an active function. It makes the active 
function's return argument available as described in "Notes" below. It is provided to 
permit writing of active functions that accept an arbitrary number of arguments (see 
"Notes" under cu_$af_arg_count above). 

USAGE 

declare cu_$af_return_arg entry (fixed bin, ptr, fixed bin(21), 
fixed bin(35)) ; 

declare return_str i ng char (max_length) varying based (rtn_str i ng_ptr) ; 
call cu_$af_return_arg (nargs, r tn_str i ng_ptr , max_length, code); 
ARGUMENTS 
nargs 

is the number of input arguments passed to the caller. (Output) 
rtn_string_ptr 

is a pointer to the varying return argument of the active function. (Output) 
max_length 

is the maximum length of the varying string pointed to by rtn_string_ptr. 
(Output) 

code 

is a standard status code. (Output) 
error_table_$nodescr 

no argument descriptors were passed to the caller or an incorrect argument 

list header was encountered. 
error_table_$not_act_f nc 

the caller was not invoked as an active function. 

NOTES 

An active function that takes an arbitrary number of arguments uses this entry point 
to return a value. It calls the entry point to get a pointer to the return argument 
and to get its maximum length. It declares the based varying string, return_string, as 
described above. It then assigns its return value to return_string. Even if 
error_table_$not_act_fnc is returned, nargs will be set to the proper value. 
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Entry: cu $af__return arg re! 

This entry point is similar to cu_$af_return_arg, but instead of looking in the 
argument list of its caller, it is given a pointer to the argument list. 

USAGE 

declare cu_$af_return_arg_rel entry (fixed bin, ptr, fixed bin(21), 
f ixed bin (35) . ptr) ; 

call cu_$af_return_arg_rel (nargs, r tn_str i ng_ptr , max_length, code, 
arg_l i st_ptr) ; 

ARGUMENTS 

nargs 

is the number of input arguments passed to the caller. (Output) 

arg_list_ptr 

is a pointer to an argument list. (Input) 

rtn_string_ptr 

is a pointer to the varying return argument of the active function. (Output) 
max_len 

is the maximum length of the varying string pointed to by rtn_string_ptr. 
(Output) 

code 

is a standard status code. (Output) 
error_table_$nodescr 

no argument descriptors were passed to the caller or an incorrect argument 

list header was encountered. 
error_table_$not_act_f nc 

the caller was not invoked as an active function. 



Entry: cu $arg count 

The cu_$arg_count entry point can be used by any procedure to determine the number 
of arguments with which it was called. 

USAGE 

declare cu_$arg_count entry (fixed bin, fixed bin (35)); 
call cu_$arg_count (arg_count, code); 
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ARGUMENTS 
arg_count 

is the number of arguments. (Output) 

code 

is a standard status code. (Output) 
error_table_$nodescr 

no argument descriptors were passed to the caller or an incorrect argument 

list header was encountered. 
error_table_$active_f unction 

the caller was invoked as an active function. 

NOTES 

Even if the code is nonzero, arg_count may still be valid. If error_table_$active_f unction 
is returned, the arg_count will be the total number of arguments, including the active 
function return argument. This number may differ from that returned by 
cu_$af_return_arg, described below. This entry point is intended for use with 
command procedures that may not be used as active functions. 

For compatibility with old programs, the code argument may be omitted. 



Entry: cu $arg count rel 

This entry point returns the number of arguments in any specified argument list. 
USAGE 

declare cu_$arg_count_rel entry (fixed bin, ptr, fixed bin (35)); 
call cu_$arg_count_rel (arg_count, arg_l i st_ptr , code); 
ARGUMENTS 
arg_count 

is the number of arguments. (Output) 
arg_list_ptr 

is a pointer to an argument list. (Input) This pointer can be obtained by calling 
cu_$arg_list_ptr, described below. 

code 

is a standard status code. (Output) 
error_table_$nodescr 

no argument descriptors were passed to the owner of the argument list or 

an incorrect argument list header was encountered. 
error_table_$acti ve_f unction 

the owner of the argument list was invoked as an active function. 
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Entry: cu $arg list ptr 

It is sometimes desirable to design a PL/ 1 procedure to accept a variable number of 
arguments of varying data types (e.g., the ioa_ subroutine). In these cases, the PL/I 
procedure must be able to interrogate its argument list directly to determine the 
number, type, and location of each argument The cu_$arg_list_ptr entry point is 
designed for use in such cases and returns a pointer to the argument list of its caller. 

USAGE 

declare cu_$arg_l i st_ptr entry (ptr); 
call cu_$arg_l i st_ptr (arg_l i st_ptr) ; 
ARGUMENTS 
arg_list_ptr 

is a pointer to the argument list of the caller. (Output) 



Entry: cu $arg ptr 

The cu_$arg_ptr entry point is used by a command or subroutine that can be called 
with a varying number of arguments, each of which is a variable-length unaligned 
character string (i.e., declared char(*)). This entry point returns a pointer to the 
character-string argument specified by the argument number and also returns the 
length of the argument. 



declare cu_$arg_ptr entry (fixed bin, ptr, fixed bin(21), fixed 
bin(35)) ; 

call cu_$arg_ptr (arg_no, arg_ptr, arg_len, code); 

ARGUMENTS 

arg_no 

is an integer specifying the number of the desired argument. (Input) 



is a pointer to the unaligned character-string argument specified by arg_no. 



arg_len 

is the length (in characters) of the argument specified by arg_no. (Output) 



USAGE 



arg_ptr 



(Output) 
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code 

is a standard status code. (Output) 
error_table_$nodescr 

the argument list does not contain descriptors. In this case, argl_len set is 

to zero. 
error_table_$noarg 

the program does not have an arg^no'th argument. In this case, arg_ptr is 
set to null and arg_len is set to zero. 

NOTES 

The command or subroutine that uses this entry point must be called with data 
descriptors for its arguments. Otherwise, the returned value of argjen is 0. If the 
argument specified by arg_no is not a character string, argjen is the value of the 
"size" field of the descriptor (the rightmost 24 bits). This entry point must not be 
called from an internal procedure that has its own stack frame or from within a 
begin block (because cu_$arg_ptr does not check for a display pointer). 



Entry! cu $s»rg ptr re! 

Some PL/ 1 procedures may need to reference arguments passed to other procedures. 
This entry point permits a procedure to reference arguments in any specified argument 
list. 

USAGE 

declare cu_$arg_ptr_rel entry (fixed bin, ptr, fixed bi n (21) , 
f i xed bin (35) » ptr) ; 

call cu_$arg_ptr_rel (arg_no, arg_ptr, arg_len, code, arg_1 i st_ptr) ; 

ARGUMENTS 

arg_no 

is an integer specifying the number of the desired argument. (Input) 
arg_ptr 

is a pointer to the unaligned character-string argument specified by arg_no. 
(Output) 

argjen 

is the length (in characters) of the argument specified by arg_no. (Output) 
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code 

is a standard status code. (Output) 
error_table_$nodescr 

the argument list does not contain descriptors. In this case, argl_len is set 

to zero. 
error_table_$noarg 

the program does not have an arg_no'th argument. In this case, ar&_ptr is 
set to null and arg_len is set to zero. 

arg_list_ptr 

is a pointer to the argument list from which this argument is being extracted. 
(Input) This pointer can be determined by calling cu_$arg_list_ptr in the 
program whose argument list is to be processed and then passing it to the 
program requesting reference to the argument list. 



Entry: cu__$caller ptr 

This entry point allows a routine to obtain a pointer to its caller. The pointer that is 
returned points to the instruction within the text section after the instruction that 
called out. 

USAGE 

declare cu_$cal 1 er_ptr entry (ptr); 
call cu_$cal 1 er_ptr (cal 1 er_ptr) ; 
ARGUMENTS 
caller_ptr 

is a pointer into the text section of the caller. (Output) If null, the invoker of 
the cu_ subroutine has no caller. 



Entry: cu__$cl 

The cu_$cl entry point is called by all standard error handlers after printing a 
diagnostic message. This entry point passes control to the procedure specified by the 
last call to cu_$set_cl_intermediary. It takes an optional argument which is passed 
directly to that procedure. If no such procedure has been specified (the norm), 
control is passed to the standard procedure, which establishes a new command level 
(see Notes below). 
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declare cu_$cl entry (1 aligned, 2 bit(l) unaligned, 2 bit (35) 
unal i gned) ; 

del 1 flags al igned, 

2 reset_sw bit (1) unaligned, 
2 mbz bit (35) unaligned; 

cal 1 cu_$cl (f lags) ; 

ARGUMENTS 

flags. reset_sw 

specifies whether the intermediary procedure should perform a "resetread" control 

order on the standard "user_i/o" I/O switch. (Input) 

"l"b do a "resetread" operation, 

"0"b do not perform a "resetread" operation. 

ri~ — 1-~ 

is reserved for future use and must be "0"b. (Input) 
NOTES 

If no argument is given, cu_$cl passes a static argument with flags. reset_sw set to 
"l"b. 

Establishing a new command level consists of saving the attachments of the standard 
I/O switches (user_input, user_output, and error_output), restoring these attachments to 
their default state, and entering a new loop of reading and executing command lines. 
If the "start" command is issued, the attachments of the standard I/O switches are 
restored to the state saved above and control is returned to the caller of cu_$cl to 
continue from the interrupted exection. If the "release" command is issued, the 
interrupted execution is aborted, the I/O switches are not restored, and control is 
returned to the previous command level. 



Entry: cu Sep 

The cu_$cp entry point, called when a Multics command line is recognized, passes the 
command line to the currently defined command processor for processing. Some 
standard Multics commands (e.g., qedx) permit the user to escape from them to 
execute other commands. In this case, the escapable command passes the line to be 
executed to the command processor. The cu_$cp entry point is called by any standard 
command that recognizes other Multics command lines. 
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USAGE 

declare cu_$cp entry (ptr, fixed bi n (21) v fixed bin(35))» 

call cu_$cp (line_ptr, line_len, code); 

ARGUMENTS 

line_ptr 

is a pointer to the beginning of a character string containing a command line to 
be processed. (Input) 

line_len 

is the length of the command line in characters. (Input) 

code 

is a standard status code or the nonstandard code 100. (Output) If an error has 
been detected, the caller of the cu_$cp entry point is not expected to print a 
diagnostic at this time since it can be expected that the command processor has 
already done so. A returned code of 100 indicates that the command line is 
blank and no ready message should be printed. 



Entry: cu Sdecode entry value 

This entry point extracts the pointer components of a PL/ 1 entry value. 
USAGE 

declare cu_$decode_entry_val ue entry (entry, ptr, ptr); 

call cu_$decode__entry_val ue (entry__value, ep_ptr, env_ptr) ; 

ARGUMENTS 

entry_value 

is the entry value to be decoded. (Input) 

ep_ptr 

is the entry point pointer, i.e., a pointer to the actual executable code. (Output) 
env_ptr 

is the environment pointer. (Output) 
NOTES 

Using the codeptr and environmentptr PL /I built-in functions are preferable to using 
the cu_$decode_entry_value subroutine. 



2-149 



AG93-05A 



Entry: cu (evaluate active string 

This entry point evaluates an active string. An active string consists of one or more 
active function invocations and their arguments. Other entries are provided for 
subsystem writers to specify the procedure to be called by this entry. 

USAGE 

declare cu_$evaluate_act ive_str ing entry (ptr, char (*) , fixed bin, 
char (♦») varying, fixed bin (35) ) » 

call cu_$evaluate_active_str i ng (info_ptr, act i ve_str i ng, string_type, 
returnj/alue, code) ; 

ARGUMENTS 

info_ptr 

is reserved for future expansion and must be null. (Input) 
active_string 

is the active string to be evaluated. (Input) It should not include the outermost 



string_type 

specifies the type of active string to be evaluated. (Input) Its possible values are: 

NORMAL_ACTIVE_STRING 

the active string return value should be rescanned for all command 
processor constructs. ([...]) 

TOKENS_ONLY_ACTIVE_STRING 

the active string return value should be rescanned only for whitespace and 
quotes. ( | C . . . J ) 

ATOMIC_ACTIVE_STRING 

the active string return value should not be rescanned. ( | | C . . . ] ) 

return_value 

is the result of the evaluation. (Output) 

code 

is a standard system status code. (Output) If its value is 
error_table_$command_line_overflow, the maximum length of the return_value 
argument was not large enough to hold the result of the evaluation. In this case, 
the result will be truncated. 

NOTES 

The constants used above for string_type are defined in the cp_active_string_types.incl.pll 
include file. The active string should not be enclosed in brackets. 
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Entry: cu $generate_call 

The cu_$generate_call entry point is used to generate a standard call to a specified 
procedure with a specified argument list This call is designed for cases in which a 
PL/ 1 procedure has explicitly built an argument list from its input data. The principal 
use of this entry is by command processors that call a command with an argument list 
built from a command line input from a terminal. 

USAGE 

declare cu_$generate_cal 1 entry (entry, ptr) ; 
call cu_$generate_cal 1 (proc_entry, a_ptr) ; 
ARGUMENTS 
proc_entry 

is the procedure entry point to be called. (Input) 
a_ptr 

is a pointer to the argument list to be passed to the called procedure. (Input) 



Entry: cu $get cl intermediary 

This entry point returns to the caller the procedure entry currently being invoked by 
a call to cu_$cl. 

USAGE 

declare cu_$get_c l_i ntermed i ary entry (entry); 
call cu_$get_cl_i ntermed i ary (proc_entry) ; 
ARGUMENTS 
proc_entry 

is the procedure entry being called by the standard error handlers after printing a 
diagnostic message. (Output) 



Entry: cu $get command name 

This entrypoint allows a routine called via the command processor to obtain the name 
used on the command line to invoke the procedure. The values returned are as 
follows: 
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Name used on command 1 i ne 



Returned Value 



name 

path>name 
name$entrypoi nt 
path>name$entrypoi nt 



name 

path>name 
name$entrypoi nt 
path>name$entrypoi nt 



USAGE 



declare cu_$get_command_name entry (ptr, fixed bin (21), fixed bin (35)) » 

call cu_$get_command_name (command_name_ptr , command__name_l ength , 
error_code) ; 

ARGUMENTS 

command_name_ptr 

Is a pointer to the command name of length command_name_length. If null, the 
command name is unavailable for the current routine. (Output) 

command_name_length 

Is the length of the returned command name. If zero the command name is 
unavailable for the current routine. (Output) 



Is a standard status code. If the command name is unavailable its value is equal 
to error_table_$no_command_name_available. (Output) 



i Entry: cu Sget command name rel 

This entrypoint allows a routine called via the command processor to obtain the name 
used on the command line to invoke the procedure. The values returned are as 
follows: 



error_code 



11/86 
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Name used on command 1 i ne 



Returned Value 



name 

path>name 
name$entrypoi nt 
path>name$entrypoi nt 



name 

path>name 
name$entrypoi nt 
path>name$entrypoi nt 



USAGE 



declare cu_$get_command_name_rel entry (ptr, fixed bin (21), 
f ixed bin (35) , ptr) ; 

call cu_$get_command_name_rel (command_name_ptr , command_name_l ength , 
error_code, argl i st_ptr) ; 

ARGUMENTS 

command_name_ptr 

Is a pointer to the command name of length command_name_length. If null, the 
command name is unavailable for the current routine. (Output) 

command_name_length 

Is the length of the returned command name. If zero the command name is 
unavailable for the current routine. (Output) 



Is a standard status code. If the command name is unavailable its value is equal 
to error_table_$no_command_name_available. (Output) 



Is a pointer to the argument list from which this argument is being extracted. 

This pointer can be determined by calling cu_$arg_list_ptr in the program whose 

argument list is to be processed and then passing it to the program requesting 
reference to the argument list. (Input) 



Entry: cu__$get__command_processor 

This entry point returns to the caller the entry value of the procedure currently being 
invoked by a call to cu_$cp. 



error_code 



arglist_ptr 



USAGE 



declare cu_$get_command_processor entry (entry) ; 



call cu_$get_command_processor (proc_entry) ; 
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ARGUMENTS 
proc_entry 

is the procedure entry point to which control is passed upon receiving a call to 
cu_$cp. (Output) 



Entry: cu $get evaluate active string 

This entry point returns to the caller the entry value of the procedure currently being 
invoked by a call to cu_$evaluate_active_string. 

USAGE 

declare cu_$get_evaluate_active_str ing entry (entry); 

call cu_$get_evaluate_act i ve_str i ng (act i ve_str i ng_procedure) ; 

ARGUMENTS 

active_string_procedure 

is the procedure entry point to which control is passed upon receiving a call to 
cu_$evaluate_active_string. (Output) 



Entry: cu $get ready mode 

This entry point returns the value of the internal static ready flags. 
USAGE 

declare cu_$get_ready_mode entry (1 aligned, 2 bit ( 1 ) unaligned, 
2 bi t (35) unal igned) ; 

del 1 mode al i gned, 

2 ready_sw bit(l) unaligned, 
2 mbz bit (35) unaligned; 

call cu_$get_ready_mode (mode) 

ARGUMENTS 

mode.ready_sw 

is the current value of the static ready switch. (Output) 

'T'b print ready message. 

"0"b do not print ready message. 

mode, mbz 

is reserved for future use and must be "0"b. (Output) 
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Entry: cu__$get_ready_procedure 

This entry point returns the entry value of the current ready procedure of the 
process. 

USAGE 

declare cu_$get_ready_procedure entry (entry); 

call cu_$get_ready_procedure (ready_entry) ; 

ARGUMENTS 

ready_entry 

is the current ready procedure. (Output) 



Entry: cu $grow stack frame 

This entry point allows its caller to allocate temporary storage by extending the caller's 
current stack frame. 

USAGE 

declare cu_$grow_stack_f rame entry (fixed bin, ptr, fixed bin (35)); 

call cu_$grow_stack_f rame (len, data_ptr, code); 

ARGUMENTS 

len 

is the length (in words) by which the caller's stack frame is to be extended. 
(Input) The standard Multics call, push, and return discipline requires that stack 
frames begin on mod 16 word boundaries. Therefore, if len is not a mod 16 
number, the stack frame is grown by the next mod 16 quantity greater than len. 

data_ptr 

is a pointer to the first location of len words allocated in the caller's stack 
frame. (Output) 

code 

is a standard status code. (Output) 
NOTES 

The cu_$grow_stack_frame and cu_$shrink_stack_f rame entry points are for advanced 
subsystems writers only and should be used only when absolutely necessary. Most PL/ 1 
programs can be written to use begin blocks to allocate extra storage in the current 
stack frame. The entry points rely on internal workings of the PL/ 1 compiler that are 
not guaranteed to continue working forever. 
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Entry: cu $level get 

The cu_$level_get entry point is used to obtain the current ring validation level. This 

entry point is normally used prior to a call to cu_$level_set to save the current 
validation level. 

USAGE 

declare cu_$ 1 evel_get entry (fixed bin); 
call cu_$ 1 evel_get (level); 
ARGUMENTS 
level 

is the current ring validation level. (Output) 



Entry: cu Slevel set 

The cu_$level_set entry point is used to change the current protection ring validation 
level. This entry point is useful for procedures that must distinguish the periods of 
time when the procedure is acting in behalf of itself (i.e., its own ring) and when it 
is acting in behalf of another procedure that can be in an outer (i.e., less privileged) 
protection ring. 

USAGE 

declare cu_$ 1 evel_set entry (fixed bin); 

call cu_$ i eve i_set (level); 

ARGUMENTS 

level 

specifies the new protection validation level and must be greater than or equal to 
the current ring number. (Input) The current ring number can be determined by 
the get_ring_ subroutine. 
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Entry: cu $make entry value 

The cu_$make_entry_value entry point constructs a PL/I entry value from a pointer 
to an entry point. The environment pointer of the entry value will be null, so the 
entry point pointer must point to an external procedure. 

USAGE 

declare cu_$make_entry_val ue entry (pointer, entry); 
call cu_$make_entry_val ue (ep_ptr, entry_va 1 ue) ; 
ARGUMENTS 
ep_ptr 

is the entry point pointer. (Input) 

entry_value 

is the entry value. (Output) 



Entry: cu Sready proc 

The ready_proc entry point is used to call the current ready procedure of the process. 
It takes an optional argument, which it passes to the ready procedure. The ready- 
procedure is automatically invoked by the listener after each command line is 
processed. The ready procedure of the standard command environment prints the ready 
message. The cu_$set_ready_procedure subroutine can be called to change the ready 
procedure. 

USAGE 

declare cu_$ready_proc entry; 
cal 1 cu_$ready_proc () ; 
or : 

del cu_$ready_proc entry (1 aligned, 2 bit(l) unaligned, 
2 bit (35) unal i gned) ; 

del 1 mode al igned, 

2 ready_sw bit(l) unaligned, 
2 mbz bit (35) unaligned; 

call cu_$ready_proc (mode); 
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ARGUMENTS 
mode, ready _sw 

specifies whether the ready procedure should print a ready message. (Input) 

"l"b print ready message 

"0"b do not print ready message 

mode.mbz 

is reserved for future use and must be "0"b. (Input) 
NOTES 

If no argument is given, a static ready switch is passed to the ready procedure. The 
default value of the static ready switch is 'T'b. The value of the static ready switch 
can be obtained using the cu_$get_ready_mode entry point and changed using the 
cu_$set_ready_mode entry point. The listener invokes the cu_$ready_proc entry point 
without an argument. The ready_off command turns off the static ready switch, the 
ready_on command turns it on, and the ready command calls the cu_$ready_proc entry 
point with an argument whose ready_sw component is "l"b. Thus, if a user-written 
ready procedure honors the ready switch, its printing of the ready message can be 
controlled by the standard ready, ready_on, and ready_off commands. 



Entry: cu Sreset cl intermediary 

This entry point resets the procedure invoked by calls to cu_$cl to the standard 
system supplied procedure. 

USAGE 

declare cu_$reset_c l_i ntermed i ary entry () ; 
call cu_$reset_c l_i ntermed i ary () ; 



Entry: cu Sreset command processor 

This entry point resets the procedure invoked by calls to cu_$cp to the standard 
system supplied procedure. 

USAGE 

declare cu_$reset_command_processor entry 0; 
call cu_$reset_command_processor () ; 
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Entry: cu_$reset__evaluate active__string 

This entry point resets the procedure invoked by calls to cu_$evaluate_active_string to 
the standard system supplied procedure. 

USAGE 

declare cu_$reset_evaluate_active_str ing entry () ; 
call cu_$reset_eval uate_act i ve_str i ng () ; 



Entry: cu $reset ready procedure 

This entry point resets the procedure invoked by calls to cu_$ready_proc to the 
standard system supplied procedure. 

USAGE 

declare cu_$reset_ready_procedure entry () ; 
call cu_$reset_ready_procedure () ; 



Entry: cu $set cl intermediary 

The Multics system provides a set of procedures to handle any error conditions that 
can be signalled within a process (see the description of the signai_ subroutine). The 
standard error handlers attempt to print an understandable diagnostic and call a 
procedure to reenter command level. However, in order to allow use of the standard 
error handling procedures in a closed subsystem environment, the error handlers do 
not call the standard error handlers directly but call the cu_$cl entry point. This 
entry point passes control to the procedure entry point currently defined by the last 
call to cu_$set_cl_intermediary. If cu_$set_cl_intermediary has never been called in 
the process, control is passed to the standard error handlers on a call to cu_$cl. 

USAGE 

declare cu_$set_c l_i ntermed i ary entry (entry); 
call cu_$set_c l_i ntermed i ary (proc_entry) ; 
ARGUMENTS 
proc_entry 

is the procedure entry to be called by the standard error handlers after printing a 
diagnostic message. (Input) 
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Entry: cu_$set command_processor 

Some standard Multics commands permit the user to escape from them to execute 
other commands. In this case, the escapable command passes the line to be executed 
to the command processor. To allow use of these escapable standard commands in a 
closed subsystem environment, instead of calling the command processor directly, the 
cu_$cp entry point is called. The latter passes control to the procedure entry point 
defined as the current command processor. The cu_$set_command_processor entry 
point allows a subsystem developer to replace the standard command processor with a 
different procedure. This mechanism can be used to ensure that the subsystem remains 
in full control and still allow subsystem users the use of many standard commands. 

USAGE 

declare cu_$set_command_processor entry (entry); 
cal 1 cu_$set_command_processor (proc_entry) ; 
ARGUMENTS 
proc_entry 

is the procedure entry point to which control is passed upon receiving a call to 
cu_$cp. (Input) 



Entry: cu $set evaluate active string 

Some standard Multics commands (e.g., compose and exec_com) permit the user to 
evaluate active strings which are a sequence of one or more active function invocations 
with their arguments. To allow the use of these commands in a closed subsystem, 
instead of calling the command processor directly to evaluate the active string, the 
cu_$evaluate_active_string entry is called. The latter passes control to the procedure 
entry point defined as the current active string evaluator. The cu_$set_evaluate_active_string 
entry point allows a subsystem developer to replace the standard active string evaluator 
with a different procedure. This mechanism can be used to insure that the subsystem 
remains in full control and still allow subsystem users the use of many standard 
commands. 

USAGE 

declare cu_$set_evaluate_active_str ing entry (entry); 

call cu_$set__evaluate_active_string (act i ve_str i ng_procedure) ; 

ARGUMENTS 

active_string_procedure 

is the procedure entry point to which control is passed upon receiving a call to 
cu_$evaluate_active_string. (Input) 
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Entry: cu Sset ready mode 

This entry point allows the user to change the value of the static ready mode. 
USAGE 

declare cu_$set__ready_mode entry (1 aligned, 2 bit(l) unaligned, 
2 bi t (35) unal igned) ; 

del 1 mode al igned, 

2 ready_sw bit(l) unaligned, 
2 mbz bit (35) unaligned; 

call cu_$set_ready_mode (mode); 
ARGUMENTS 

mode, ready _sw 

is the new value of the static ready switch. (Input) 

'T'b print ready message 

"0"b do not print ready message 

mode.mbz 

is reserved for future use and must be "0"b. (Input) 



Entry: cu $set_ready procedure 

This entry point allows the user to change the ready procedure invoked by 
cu_$ready_proc. 

USAGE 

declare cu_$set_ready_procedure entry (entry); 
call cu_$set_ready_procedure (ready_entry) ; 
ARGUMENTS 
ready_entry 

is the procedure entry point that is to become the new ready procedure of the 
process. (Input) 



2-159 



AG93-05 



cu_ 



Entry: cu Sshrink stack frame 

This entry point allows its caller to deallocate temporary storage by reducing the 
caller's current stack frame. Such storage must have been allocated via a call to 
cu_$grow_stack_f rame. 

USAGE 

declare cu_$shr i nk_stack_f rame entry (ptr, fixed bin(35)); 

call cu_$shr i nk_stack_f rame (ptr, code); 

ARGUMENTS 

ptr 

is a pointer to the first word of the storage to be deallocated. (Input) It must 
point to a mod 16 word boundary. The stack frame from the word indicated by 
ptr to the end of the frame is deallocated. 

code 

is a standard status code. (Output) 



Entry: cu Sstack frame ptr 

The cu_$stack_frame_ptr entry point returns a pointer to the stack frame of its caller. 
The stackframeptr builtin function should be used to get this information in PL/ 1 
programs, since it is more efficient 

USAGE 

declare cu_$stack_f rame_ptr entry (ptr); 
call cu_$stack_f rame_ptr (stack_ptr) ; 
ARGUMENTS 
stack_ptr 

is a pointer to the stack frame of its caller. (Output) 
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Entry: cu Sstack frame size 

The cu_$stack_frame_size entry point returns the size (in words) of the stack frame 
of its caller. 

USAGE 

declare cu_$stack_f rame_s i ze entry (fixed bin) ; 
call cu_$stack_f rame_size (size); 
ARGUMENTS 
size 

is the size (in words) of the caller's stack frame. (Output) 



Name: cv bin 

The cv_bin_ subroutine converts the binary representation of an integer (of any base) 
to a 12-character ASCII string. 

USAGE 

declare cv_b i n_ entry (fixed bin, char (12) aligned, fixed bin); 

call cv_bin_ (n, string, base); 

ARGUMENTS 

n 

is the binary integer to be converted. (Input) 
string 

is the ASCII equivalent of n. (Output) 

base 

is the base to use in converting the binary integer (e.g., base is 10 for decimal 
integers). (Input) 
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Entry: cv bin $dec 

This entry point converts the binary representation of an integer of base 10 to a 
12-character ASCII string. 

USAGE 

declare cv_bin_$dec entry (fixed bin, char (12) aligned); 

call cv_bin_$dec (n, string); 

ARGUMENTS 

n 

is the binary integer to be converted. (Input) 
string 

is the ASCII equivalent of n. (Output) 

A/rtTCO 

This function can be performed more efficiently in PL/ 1 by: 
string = ltrim (char (n) ) ; 

Entry: cv bin $oct 

This entry point converts the binary representation of an octal integer to a 
12-character ASCII string. 

USAGE 

declare cv_bin_$oct entry (fixed bin, char (12) aligned); 

call cv_bin_$oct (n, string); 

ARGUMENTS 

n 

is the binary integer to be converted. (Input) 
string 

is the ASCII equivalent of n. (Output) 

« i r~\T r-r< 

IVL/I CO 

If the character-string representation of the number exceeds 12 characters, then only 
the low-order 12 digits are returned. 
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Name: cv dee 

The cv_dec_ function accepts an ASCII representation of a decimal integer and returns 
the fixed binary(35) representation of that number. (See also cv_dec_check_.) 

USAGE 

declare cv__dec_ entry (char(*)) returns (fixed bin (35)); 

a = cv_dec_ (string); 

ARGUMENTS 

string 

is the string to be converted. (Input) 

a 

is the result of the conversion. (Output) 
NOTES 

If string is not a proper character representation of a decimal number, a will contain 
the converted value of the string up to, but not including, the incorrect character 
within the string. 

This function can be performed more efficiently in PL/ 1 by: 
a = convert (a, string); 



Name: cv dec check 

This function differs from cv_dec_ only in that a code is returned indicating the 
possibility of a conversion error. (See also cv_dec_.) 

USAGE 

declare cv_dec_check_ entry (char (*) , fixed bin (35)) 
returns (fixed bin (35))* 

a = cv_dec_check_ (string, code); 
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ARGUMENTS 
string 

is the string to be converted. (Input) 

code 

is a code that equals 0 if no error has occurred; otherwise, it is the index of the 
character of the input string that terminated the conversion. See "Notes" below. 
(Output) 

a 

is the result of the conversion. (Output) 
NOTES 

Code is not a standard status code and, therefore, cannot be passed to com_err_ and 
other subroutines that accept only standard status codes. 

This function can be performed more efficiently in PL/ 1 by: 

on convers i on, s i ze goto badnumber; 
a = convert (a, string); 
revert convers i on, s i ze; 



badnumber : 

call com_err_ (error_table_$bad_conversion, proc, string); 
return; 
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Name: cv dir mode 

The cv_dir_mode_ subroutine converts a character string containing access modes for 
directories into a bit string used by the ACL entries. 



declare cv_d i r_mode_ entry (char (*) , bit(*), fixed bin(35))» 
call cv_di r_mode_ (char_modes, bit_modes, code); 
ARGUMENTS 
char_modes 

are the character string access modes. (Input) 
bit_modes 

are the bit string access modes. (Output) 

code 

is a standard status code. (Output) It can be: 
error_table_$bad_acl_mode 

if char_modes contains an invalid directory access mode character 



If char_modes is "null" or "n", bit_modes is set to "0"b. The mode characters in 
char_modes can occur in any order. Spaces are ignored. The following table indicates 
which bit in bit_modes is turned on when the access mode character is found. 



USAGE 



NOTES 



Access Mode 



Bit in bit modes 



s 



m 



a 



2 
3 



These values are declared in access_mode_values.incl.pll. 
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Name: cv entry 

The cv_entry_ function converts a virtual entry to an entry value. A virtual entry is 
a character-string representation of an entry value. The types of virtual entries 
accepted are described under "Virtual Entries" below. 

USAGE 

declare cv_entry_ entry (char (*) , ptr, fixed bin (35)) returns (entry); 
entry_value = cv_entry_ (ventry, ref erenc i ng_ptr , code); 
ARGUMENTS 
ventry 

is the virtual entry to be converted. See "Virtual Entries" below for more 
information. (Input) 

referencing_ptr 

is a pointer to a segment in the referencing directory = This directory is searched 
according to the referencing_dir search rule to find the entry. A null pointer 
may be given if the referencing_dir search rule is not to be used. (Input) 

code 

is a standard status code. (Output) 
entry_value 

is the entry value that results from the conversion. (Output) 
VIRTUAL ENTRIES 

The cv_entry_ function converts virtual entries that contain one or two components — 
| a segment identifier and an optional offset into the segment. Altogether, eleven forms 
are accepted. They are shown in the table below. 

In the table that follows, W is an octal word offset from the beginning of the 
segment. It may have a value from 0 to 777777 inclusive. 
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path | W 

entry at octal word W of segment identified by absolute or relative pathname 
path. 

path | 

same as pathjO. 

path | entry_pt 

entry at word identified by entry point entry_pt in the object file (segment or 
MSF) identified by path. 

dir>entry$entry_pt 

entry at word identified by entry point entry_pt in the the object file identified i 
by pathname dir>entry. 

<dir>entry$entry_pt 

entry at word identified by entry point entry_pt in the object file identified by | 
pathname <dir>entry. 

<entry$entry_pt 

entry at word identified by entry point entry_pt in the object file identified by | 
pathname <entry. 

path 

same as path | [entry path]. 
ref_name$entry_pt 

entry at word identified by entry point entry_pt in the file found via search | 

rules whose reference name is ref_name= 

ref_name$W 

entry at octal word W of segment found via search rules whose reference name is 
ref_name. 

ref_name$ 

same as ref_name$0. 

ref_name 

same as ref_name$ref_name but like "path" if it contains ">" or "<" characters. 
NOTES 

Use of a pathname in a virtual entry causes the referenced segment to be initiated 
with a reference name equal to its final entryname. Name duplication errors occurring 
during the initiation are resolved by terminating the previously known name. 

The referencing_ptr is used in a call to the hcs_$make_entry entry point. 

The cv_entry_ function returns an entry value that may be used in a call to 
cu_$generate_call. If an entry pointer is required, rather than an entry variable, use 
the cv_ptr_ subroutine. 
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A virtual entry not containing the $ or | characters is interpreted as a pathname if it 
contains a > or < character, otherwise, it is a reference name. 



Name: cv error subroutine 

Entry: cv_error subroutine$name 

This entry point converts an error name (e.g., error_table_$badarg) to an error code. 
USAGE 

del cv_error_$name entry (char (*) , fixed bin (35). fixed bin (35)); 
call cv_error_$name (error_name, conver ted__code, code); 
ARGUMENTS 
error_name 

is the name of the error to be converted. (Input) 

converted_code 

is the result of converting error_name. (Output) 

code 

is a standard system status code. If code is non-zero, converted_code is 
undefined. (Output) 



Name: cv float 

The cv_float_ subroutine converts an ASCII representation of a floating point number 
and returns a single precision floating point representation. If an illegal character is 
encountered, its index in the string is returned and the number is set to O.OeO. (See 
also cv_float_double_.) 
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USAGE 

declare cv_f loat_ entry (char (*) , fixed bin (35) 5 returns (float bin); 

a * cv_float_ (string, code); 

ARGUMENTS 

string 

is the string to be converted. (Input) 

code 

is the index in string of the first illegal character, if found; otherwise it is zero. 
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is the result of the conversion. (Output) 
NOTES 

Code is not a standard status code. Therefore, it can not be passed to com_err_ and 
other subroutines that accept only standard status codes. 

This function can be performed more efficiently in PL/I by: 

on conversion, size goto badnumber; 
a - convert (a, string); 
revert conversion, size; 



badnumber: 

call com_err_ (error_tabl e_$bad_convers ion, proc, string); 
return; 



Name: cv float double 

The cv_float_double_ subroutine converts an ASCII representation of a floating point 
number and returns a double precision floating point representation. If an illegal 
character is encountered, its index in the string is returned and the number is set to 
O.OeO. (See also cv_float_.) 

USAGE 

declare cv_f 1 oat_doubl e_ entry (char (*) , fixed bin(35)) returns 
(float bin (63)) ; 

a = cv_f loat_doubl e_ (string, code); 

ARGUMENTS 

string 

is the string to be converted. (Input) 

code 

is the index in string of the first illegal character, if found; otherwise it is zero. 

a 

is the result of the conversion. (Output) 
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NOTES 

Code is not a standard status code. Therefore, it can not be passed to com_err_ and 
other subroutines that accept only standard status codes. 

This function can be performed more efficiently in PL/ 1 by: 

on convers i on, s i ze goto badnumber; 
a « convert (a, string); 
revert convers ion, s i ze; 



badnumber : 

call com_err_ (error_table_$bad_conversion, proc, string); 
return; 



Name: cv fstime 

Given a file system time value, this function returns a Multics clock value. 
USAGE 

declare cv_fstime_ entry (bit (36) aligned) 
returns (fixed bin(7D); 

clock_value = cv_fstime_ (fstime) ; 

ARGUMENTS 

fstime 

the file system time to be converted. (Input) Such values are returned by such 
entry points as hcs_$status_, hcs_$status_long, hcs_$star_list, hcs_$star_dir_list. 

ciock_vaiue 

the Multics clock value which corresponds to fstime. (Output) 
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Name: cv hex 

The cv_hex_ function takes an ASCII representation of a hexadecimal integer and 
returns the fixed binary(35) representation of that number. The ASCII representation 
may contain either uppercase or lowercase characters. (See also cv_hex_check_.) 

USAGE 

declare cv_hex_ entry (char(*)) returns (fixed bin (35)); 

a = cv_hex_ (string); 

ARGUMENTS 

string 

is the string to be converted. It must be nonvarying. (Input) 

a 

is the result of the conversion. (Output) 



Name: cv hex__check 

This function differs from the cv_hex_ function only in that a code is returned 
indicating the possibility of a conversion error, (See also cv_hex_.) 

USAGE 

declare cv_hex_check_ entry (char (*) , fixed bin(35))» 
returns (fixed bin (35)) I 

a = cv_hex_check_ (string, code); 

ARGUMENTS 

string 

is the string to be converted. It must be nonvarying. (Input) 

code 

is a code that equals 0 if no error occurred; otherwise, it is the index of the 
character that terminated the conversion. See "Note" below. (Output) 

a 

is the result of the conversion. (Output) 
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NOTES 



Code is not a standard status code and, therefore, cannot be passed to com_err_ and 
other subroutines that accept only standard status codes. 



Name: cv mode 

The cv_mode_ subroutine converts a character string containing access modes for 
segments into a bit string used by the ACL entries. 



declare cv_mode_ entry (char (*) , bit(*), fixed bin (35)); 
call cv_mode_ (char_modes, bit_modes, code); 
ARGUMENTS 
char_modes 

are the character string access modes. (Input) 
bit_modes 

are the bit string access modes. (Output) 

code 

is a standard status code. (Output) It can be: 
error_table_$bad_acl_mode 

if char_mode contains an invalid segment access mode character. 



If char_modes is "null" or "n", bit_modes is set to "0"b. The mode characters in 
char_modes may occur in any order. Spaces are ignored. The following table indicates 
what bit in bit_modes is turned on when the access mode character is found. 



USAGE 



NOTES 



Access Mode 



Bit in bit modes 



r 



w 



e 



2 
3 



These values are declared in access_mode_values.incl.pll. 
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Name: cv oct 

The cv_oct_ function takes an ASCII representation of an octal integer and returns 
the fixed binary (35) representation of that number. (See also cv_oct_check_.) 

USAGE 

declare cv_oct_ entry (char(*)) returns (fixed bin(35))» 

a = cv_oct_ (string); 

ARGUMENTS 

string 

is the string to be converted. (Input) 

a 

is the result of the conversion. (Output) 



Name: cv oct check 

This function differs from the cv_oct_ function only in that a code is returned 
indicating the possibility of a conversion error. (See also cv_oct_.) 

USAGE 

declare cv_oct_check_ entry (char (*) , fixed bin(35)) returns 
(fixed bin (35)) ; 

a = cv_oct_check_ (string, code); 

ARGUMENTS 

string 

is the string to be converted. It must be nonvarying. (Input) 

code 

is a code that equals 0 if no error occurred; otherwise it is the index of the 
character that terminated the conversion. See "Notes" below. (Output) 

a 

is the result of the conversion. (Output) 
NOTES 

Code is not a standard status code and, therefore, cannot be passed to com_err_ and 
other subroutines that accept only standard status codes. 
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Name: cv ptr 

The cv_ptr_ function converts a virtual pointer to a pointer value. A virtual pointer 
is a character-string representation of a pointer value. The types of virtual pointers 
accepted are described under "Virtual Pointers" below. 

USAGE 

declare cv_ptr_ entry (char (*) , fixed bin (35)) returns (ptr); 

ptr_value = cv_ptr_ (vptr, code); 

ARGUMENTS 

vptr 

is the virtual pointer to be converted. See "Virtual Pointers" below for more 
information. (Input) 

code 

is a standard status code. (Output) 
ptr_value 

is the pointer that results from the conversion. (Output) 



Entry: cv ptr Sterminate 

This entry point is called to terminate the segment that has been initiated by a 
previous call to cv_ptr_. 

USAGE 

declare cv_ptr_$termi nate (ptr); 
call cv_ptr_$termi nate (ptr_value); 
ARGUMENTS 
ptr_value 

is the pointer returned by the previous call to cv_ptr_. (Input) 
NOTES 

Pointers returned by the cv_ptr_ function cannot be used as entry pointers. The 
cv_ptr_ function constructs the returned pointer to a segment in a way that avoids 
copying of the segment's linkage and internal static data into the combined linkage 
area. The cv_entry„ function is used to convert virtual entries to an entry value. 
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The segment pointed to by the returned ptr_value is initiated with a null reference 
name. The cv_ptr_$terminate entry point should be called to terminate this null 
reference name. 

VIRTUAL POINTERS 

The cv_ptr_ function converts virtual pointers that contain one or two components — 
a segment identifier and an optional offset into the segment. Altogether, seventeen 
forms are accepted. They are shown below. 

In the list that follows, W is an octal word offset from the beginning of the segment; 
it can have a value from 0 to 777777 inclusive. B is a decimal bit offset within the 
word; it can have a value from 0 to 35 inclusive. The possible forms are: 

path|W(B) 

points to octal word W, decimal bit B, of the segment or multisegment file 
(MSF) identified by absolute or relative pathname path. If the path you give 
identifies a MSF, the offset given is in component 0 of the MSF. 

path|W 

same as path|W(0). 

path | 

same as path 1 0(0). 

path 

same as path 1 0(0). 
path | entry_pt 

points to the word identified by entry point entry_pt in the object file (segment 
or MSF) identified by path. 

dir>entry$entry_pt 

points to the word identified by entry point entry_pt in the object file identified | 
by pathname dir>entry. 

<dir>entry$entry_pt 

points to the word identified by entry point entry_pt in the object file identified | 
by pathname <dir>entry. 

<entry$entry__pt 

points to the word identified by entry point entry_pt in the object file identified | 
by pathname <entry. 

ref_name$entry_pt 

points to the word identified by entry point entry_pt in the file whose reference | 
name is ref_name. 
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ref_name$W(B) 

points to the octal word W, decimal bit B, of the segment or MSF whose 
reference name is ref_name. If ref_name is a reference name on an MSF (i.e., 
on component 0 of the MSF), the word and bit offsets are applied within 
component 0. 

ref_name$W 

same as ref_name$W(0). 

ref_name$ 

same as ref_name$0(0). 

segno|W(B) 

points to the octal word W, decimal bit B, of the segment whose octal segment 
number is segno. 

segno | W 

same as segno |W(0). 

segno | 

same as segno j 0(0). 

segno 

same as segno 1 0(0). 

segno | entry _pt 

points to the word identified by entry point entry_pt in the segment whose octal 
segment number is segno. If segno identifies component 0 of an object MSF, the 
pointer returned may not point within the segment identified, since the target of 
a definition in component 0 of an object MSF will be in another component of 
the object MSF. 

A null pointer is represented by the virtual pointer 77777 1 1, by -1|1, or by -1. 

A virtual entry not containing the $ or | characters is interpreted as a pathname if it 
contains a > or < character, otherwise, it is a reference name. 

| Archive component pathnames are permitted. 
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Name: cv rep attributes... 

The cv_rcp_attributes_ subroutine contains several entry points that are useful in 
manipulating RCP resource attribute specifications and descriptions. RCP resource 
attribute descriptions are printable strings that describe the attributes of resources 
(devices and volumes). 

See the Programmer's Reference Manual for a description of the Resource Control 
Facility. 

RCP resource attribute specifications are encoded representations of attribute descriptions. 
They can be absolute, relative, or multiple. An absolute attribute specification 
represents a complete and consistent state of all the attributes of a resource. A 
relative attribute description represents a desired modification to the state of all the 
attributes of a resource, and must be applied to an absolute attribute specification to 
produce the desired change in that absolute specification. A multiple attribute 
specification does not represent a consistent state of all the attributes of a resource at 
any given time, but is useful for representing the union of all such consistent states, 
i.e., potential attributes. 



Entry: cv rcp — .attr ibutes_$f rom string 

This entry point accepts a printable RCP attribute description and produces an RCP 
attribute specification. 

USAGE 

declare cv_rcp_attr i butes_$f roiri_str ing entry (char (*) , 
(2) bit (72), char (*) varying, fixed bin (35)); 

call cv_rcp_attr ibutes_$f rom_str i ng (type, attributes, string, code); 
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ARGUMENTS 
type 

specifies the type of resource to which attributes apply. (Input) 
attributes 

is an RCP attribute specification (see "Notes" below). (Output) 
string 

is a printable RCP attribute description. (Input) 

code 

is a standard status code. (Output) 



Entry: c v rep attributes $f rom string rel 

This entry point generates a relative attribute specification that can later be applied to 
attribute specifications of specific resources via the cv_rcp_attributes_$modify_rel entry 
point 



declare cv_rcp_at.tr i butes_$f rom_str i ng_rel entry (char (*) , 

char (*) varying, bit (72) dimension (k) , fixed bin (35)); 

call cv_rcp_attr ibutes_$f rom_str i ng_rel (type, string, rel_attr i butes, 
code) ; 

ARGUMENTS 

type 

specifies the type of resource to which string applies. (Input) 
string 

is a printable RCP attribute description. (Input) 
rel_attributes 

is the relative RCP attribute specification. (Output) 

code 

is a standard status code. (Output) 



USAGE 
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Entry: cv rcp__attributes Smodify 

This entry point applies a printable RCP resource attribute description (representing a 
relative attribute specification) to a given resource specification and returns a new 
attribute specification. The resulting attribute specification consists of the original 
attribute specification modified by the attributes specified in the printable description. 

USAGE 

declare cv_rcp_attr i butes_$mod i f y entry (char (*) , bit (72) d imens i on (2) , 
char (*) varying, bit (72) dimension (2) , fixed bin (35)) J 

call cv_rcp_attr ibutes_$modi f y (type, attributes, string, 
new_attr ibutes, code); 

ARGUMENTS 

type 

specifies the type of resource to which attributes and string apply. (Input) 
attributes 

is an absolute RCP attribute specification. (Input) 
string 

is a printable RCP attribute description that modifies attributes. (Input) 
new_attributes 

is the new absolute RCP attribute specification. (Output) 

code 

is a standard status code. (Output) 



Entry: cv rep attributes $modify_rel 

This entry point applies a relative attribute specification produced by the 
cv_rcp_attributes_$from_string_rel entry point to an absolute attribute specification of 
a specific resource. 

USAGE 

declare cv_rcp_attr ibutes_$mod i f y_re1 entry (bit (72) dimension (2), 
bit (72) dimension (4), bit (72) dimension (2)); 

call cv_rcp_attr ibutes_$mod i f y_rel (attributes, rel_attr i butes , 
new attr i butes) ; 
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ARGUMENTS 
attributes 

is an absolute attribute specification. (Input) 
rel_attributes 

is a relative attribute specification to be applied to attributes. (Input) 
new_attributes 

is the resulting absolute attribute specification. (Output) 
NOTES 

The caller must ensure that attributes and rel_attributes refer to the same resource 
type, i.e., that they are generated by previous calls to cv_rcp_attributes_ where the 
type arguments are identical. 



Entry: cv rep attributes Sprotected change 

This entry point accepts an absolute attribute specification for a resource and a 
relative attribute specification that is to modify it. It returns a value expressing 
whether or not this modification affects protected attributes of the resource. No 
modification is actually attempted by this entry. 

USAGE 

declare cv_rcp_attr S butes_$protected_change entry (bit (72) 

d imens i on (2) , bit (72) d i mens i on (4) ) returns (bit (1) aligned); 

protected_change- = cv_rcp_attr ibutes_$protected_change (attributes, 
rel_attr i butes) ; 

ARGUMENTS 

attributes 

is an RCP attribute specification. (Input) 
rel_attributes 

is a relative attribute specification to be applied to attributes. (Input) 
protected_change 

is "l"b if this operation modifies protected attributes of the resource; otherwise, it 
is "0"b. (Output) 
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Entry: cv_rcp attributes $reduce_impli cations 

This entry point accepts an attribute specification for a volume and returns the 
necessary minimal attribute specification that a device must possess to be able to 
accept the volume. 

USAGE 

declare cv_rcp_attr ibutes_$reduce_impl i cat ions entry (char (*) , bit (72) 
dimension (2) , char (*) , bit (72) dimension (k) , fixed bin (35)); 

call cv_rcp_attr i butes_$reduce_impl i cat ions (vol_type, vol_attr ibutes, 
dev__type, dev_attr ibutes, code); 

ARGUMENTS 

vol_type 

specifies the type of volume from which vol_attributes is obtained. (Input) 
vol_attributes 

is an absolute attribute specification for the volume type specified. (Input) 
dev_type 

is the resource type of the device that accepts the given volume type. (Output) 
dev_attributes 

is a minimal relative attribute specification for a device capable of accepting a 
volume with the given attributes. (Output) 

code 

is a standard status code. (Output) 



Entry: cv rep attributes Stest valid 

This entry point determines whether a given attribute specification is absolute, relative, 
multiple, or invalid. 

USAGE 

declare cv_rcp_attr i butes_$test_va 1 i d entry (char (*) , bit 72 
dimension (2), fixed bin, fixed bin (35)); 

call cv_rcp_attr i butes_$test_val id (type, attributes, validity, code); 
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ARGUMENTS 
type 

specifies the type of resource to which attributes apply. (Input) 
attributes 

is an RCP attribute specification. (Input) 
validity 

shows whether the attribute specification is absolute, relative, or multiple. (Output) 

0 is an absolute attribute specification 

1 is a relative attribute specification 

2 is a multiple attribute specification 

code 

is a standard status code. (Output) 



Entry: cv rep attributes $to string 

This entry point takes an RCP resource attribute specification and produces a printable 
RCP attribute description. 



USAGE 

declare cv_rcp_attr i butes_$to_str i ng entry (char (*) , bit (72) 
dimension (2), char (*) varying, fixed bin (35)); 

call cv_rcp_attr ibutes_$to_str i ng (type, attributes, string, code); 

ARGUMENTS 

type 

specifies the type of resource from which attributes are obtained, e.g., disk_drive 
(see "Notes" below). (Input) 

attributes 

is an RCP attribute specification (see "Notes" below). (Input) 
string 

is a printable RCP attribute description. (Output) 

code 

is a standard status code. (Output) 
NOTES 

A list of defined resource types can be obtained via the list_resource_types command. 
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Name: cv_ userid 

The cv_userid_ subroutine converts a character string containing an abbreviated User_id 
into one containing all three components, i.e. Person_id.Project_id.tag. 

USAGE 

declare cv__userid_ entry (char(*)) returns (char (32) ) ; 

user_id = cv__userid_ (string); 

ARGUMENTS 

string 

is the abbreviated User_id. (Input) 
user_id 

is a User_id containing all three components. (Output) 
NOTES 

The Person_id, Projected and tag components are truncated to 20, 9 and 1 characters, 
respectively. An asterisk ("*") is supplied for missing components. 

EXAMPLES 

Abbreviated User id Full User id 



Smi th. Project .a Smi th. Project .a 

Smi th .Project Smi th. Project .* 

Smith Smith.*.* 

.Project *. Project.* 



Name: date time 

The date_time_ system is a utility which encodes, decodes, adjusts, or formats a 
Muitics standard calendar clock value. The clock reading is assumed to be in 
microseconds relative to 1901-01-01 0:00 gmt The ASCII times involved may be one 
of several languages and in a choice of time zones around the world. 
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Entry: date_time Sdate time 

The date_time_ subroutine converts a system clock value to ASCII representation. It 
will be in terms of the process default language and zone. 

USAGE 

declare date_time_ entry (fixed bin (71), char(*)); 

call date_time_ (clock, str) ; 

ARGUMENTS 

clock 

is the clock value to be formatted. (Input) 

str 

is the resultant character string. (Output) 
NOTES 

The format string which produces the resultant string is: 

"~my/~dm/~yc ~Hd~99v.9MH ^xxxxza^xxxxda" 

which produces strings like this: 

mm/dd/yy HHMM.M zzzddd 
07/1V83 11*35. mst Thu 

See date_time_$format for a description of time format strings. 

The ASCII representation of time, which date_time_ attempts to return in string, is 24 
characters long. If string is declared by the caller with a length of N and N is less 
than 24, then only the first N characters are returned. If N is greater than 24, then 
the result is returned padded on the right with spaces. 

If clock is not a valid date, "01/01/01 0000.0 gmt Tue" is returned. 
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Entry: date_time__$f ormat 

This entry does a generalized formatting of a Multics standard calendar clock value. 
A format string is supplied which describes the layout and content of the desired 
result The zone and/or language in which the result is to be displayed may be 
specified. 

USAGE 

declare da te_time_$ format entry (char (*) , fixed bin (71), char (*) , 
char(*)) returns (char (250) var) ; 

result = date_t ime_$f ormat (format, clock, zone, lang); 

ARGUMENTS 

format 

either a keyword, or an ioa-like control string describing the desired result in 
terms of literal characters and date/ time selectors. (Input) See Notes on Time 
Format, below. 

clock 

a clock value to be displayed. (Output) 

zone 

the short name of the zone in which output time value is expressed. (Input) 
"system_zone" means use the system default zone. "" means use the per-process 
default zone. (Input) 

lang 

the language in which month names, day names and time zones are expressed. 
(Input) "system_lang" means use the system default time language. means use 
per-process default time language. 

result 

is the string which is the result of the conversion. (Output) 
ERROR HANDLING 

There are many errors which may occur while trying to format a string. These will 
seldom occur in a thoroughly debugged environment, so there is no error code used to 
report the (usual) success. Instead, the sub_err_ mechanism is used when an error 
occurs. The information in the sub_error_info structure is generally quite explicit as to 
the type of error and usually quite detailed in its explanation. Within a sub_error_ 
handler it is quite easy to display this data. First, sub_error_info.name will contain 
"date_time_$f ormat". Then a nice-looking message will be produced by: 

call coin_err_ (sub_error_i rifo.5tatus_code, M my_name !! , !! ~a", 
sub_error_i nf o. i nf o_str i ng) ; 
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A detailed message which could result from this is: 

my_name: The picture contains a syntax error. 
Format is: "^yc-^Smy-^Sdm" 
error at: 

This is the set of values which may be present in the status_code field: 

error_table_$badcall 

the environment was not set up properly before calling this procedure. 

error_table_$bad_conversion 

a conversion condition occurred while trying to convert a value. 

error_table_$dt_bad_format_selector 

unrecognized selector in format string. 

error_table_$dt_date_too_big 

the date given is after 9999-12-3 1_23: 59:59. 999999_GMT. 

error_table_$dt_date_too_small 

the date given is before 0001-01-01_00:00:00.000000_GMT. 

error_table_$dt_no_f ormat_selector 

the format string contains no selectors and is not a known keyword. 

error_table_$dt_unknown_time_language 

the language specified by the caller was not found in time_info_. 

error_table_$dt_year_too_big 

the clock value given, when converted to the specified time zone, is after the 
year 9999. 

error_table_$dt_year_too_small 

the clock value given, when converted to the specified time zone, is before the 
year 0001. 

error_table_$picture_bad 

the picture supplied is in error. 

error_table_$picture_scale 

the picture scale factor not in the range -128:+127. 
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error_table_$picture_too_big 

the normalized picture exceeds 64 characters. 

error_table_$size_error 

the size condition occurred during processing. 

error_table_$unimplemented_version 

a structure is not a version this procedure can handle. 

error_table_$unknown_zone 

the time zone specified by the caller was not found in time_info_. 

NOTES ON TIME FORMAT 

By means of convert_date_to_binary_, an input time string is converted to internal 
form. This is the usual form for storing dates in data bases. To convert one of these 
into a readable form, a programmer may call upon date_time_ to get a 24-character 
form like this: 

03/] i» /79 0000.0 est Fri 

But when other formats are needed, date_time_$format is available. It takes a clock 
value and a control string describing the format wanted and returns a string ready for 
printing. 

Most date/ time outputs from the system software are usable as date/ time inputs to 
system software. But, the time format mechanism is highly flexible and may easily 
generate formats which are not recognizable. Worse yet are the strings which are 
apparently recognized but which are ambiguous. A point in case is the commonly used 
string "7/1/82". In the United States, this means the 7th month, first day; but many 
places in Europe, this would be taken to mean the 7th day of the first month. 
Multics follows the United States interpretation. 

TIME FORMAT 

The control string to date_time_$format is either a keyword or a character string 
consisting of text and /or selectors. The selectors are always identified by a leading 
circumflex character ( A ). There are 2 types of selectors: A <keyword>, which allows a 
keyword to be imbedded within a format; and the general form A XX. XX is a 2 
letter code which specifies what information is wanted. An optional PL/I picture 
specification may be placed between the A and XX if the default form is not 
adequate. If the control string does not contain any circumflex characters, it must 
then be one of the known set of keywords. Each keyword identifies a control string 
for a predetermined format named by that keyword. 
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LIST OF FORMAT KEYWORDS 



all 

A 9999y c — A my — A dm A Hd: A MH: A 99. (6)9UM A zd_ A za_ A da A fi 

A (6)9fw A ma dy A dy dc A dc Uc A Uc 

calendar clock 

A 9999yc- A my- A dm_ A Hd: A MH: A 99.(6)9UM_ A za_ A da 

clock 

A 9999yc- A my- A dm A Hd: A MH: A 99.(6)9UM A za A da 

date 

the process default value for date 
date_time 

the process default value for date and time 

iso_date 

A 9999yc- A my- A dm 

iso_date_time 

A 9999yc- A my- A dm A Hd: A MH: A SM A za 

iso_long_date 

A 9999yc- A my- A dm A da 

iso_long_date_time 

A 9999yc- A my- A dm A Hd: A MH: A 99.(6)9UM A za 

iso_long_time 

A Hd: A MH: A 99.(6)9UM 

iso_time 

A Hd: A MH: A SM 

multics_date 

A my/ A dm/ A yc 

multics_date_time 

A my/ A dm/ A yc A Hd A 99v,9MH A xxxxza A xxxda 

multics_time 
A Hd: A MH 

requested 

A yc A my A dm A Hd A MH A 99. (6)9UM 
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system_date_time 

the system default value for date and time 

system_date 

the system default value for date 

system_time 

the system default value for time 

time 

the process default value for time 

A site may change the "system" keywords. To list the "system" keywords for your 
site, type: 

pr i nt_t ime_def aul ts -system 

For an application which depends upon the historic date/ time formats, the 3 builtin 
"multics" keywords are available. 



Processing of a control string proceeds by scanning the control string until a 
circumflex is found, or the end of the string is reached. Any text (including any 
blanks) passed over is copied to the output string. The selector is then interpreted and 
executed. This causes a datum from the input clock value to be edited into the output 
string. Processing continues in this way until the control string is exhausted. 



Dates and times placed in the output string may be expressed in units of years, 
months, weeks, days, hours, minutes, seconds and microseconds. The total calendar 
value can be expressed as a single unit. For example, the calendar value representing 
79-09-08 9:42A GMT could be expressed as 1979 years, as 722702 days, or as 
722702.112499 days. This is the set of "total" selectors: 

Aye 

total number of Years in the Calendar value. 

A mc 

total number of Months in the Calendar value. 

Mc 

total number of Days in the Calendar value. 

A Hc 

total number of Hours in the Calendar value. 

A Mc 

total number of Minutes in the Calendar value. 
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A Sc 

total number of Seconds in the Calendar value. 

A Uc 

total number of Microseconds in the Calendar value. 

Dates and times may also be expressed as the number of units remaining after a 
larger unit has been removed from the calendar value. For example, 09/08/79 09:42 
includes units for 9th month of the year, 8th day of the month, 9th hour of the day, 
and 42nd minute of the hour. The following are the most common: 

A my 

Month in the Year 

A dm 

Day of the Month. 

A dw 

Day of the Week. 

A Hd 

Hour of the Day (24-hour format). 

A Hh 

Hour in Half -day (12-hour format). 
A MH 

Minute of the Hour. 

A SM 

Second of the Minute. 

A US 

Microsecond of the Second 

There are several items of date/ time data which are nonnumeric, such as day of week, 
day of month, and time zone used for conversion. 

A mn 

Month Name 

A ma 

Month name, Abbreviated 

A dn 

Day Name 

A da 

Day name, Abbreviated 
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A zn 

time Zone Name 

A za 

time Zone name, Abbreviated 

A zd 

Zone Differential (char(5)) 

A mi 

Meridiem Indicator ("A" or "P") 

A fi 

Fiscal Indicator ("FW" in english) 

The selectors of numeric data are, in general, made up of 2 letters taken from this 
sequence: cymwdHMSU 

The letters stand for calendar, year, month, week, day, Hour, Minute, Second, and 
microsecond. All 81 combinations are not, however, valid. The form can generally be 
read as "unit of unit", i.e. "seconds of week". The first unit is always smaller than 
the second one. In trying to keep the specifiers reasonably mnemonic (in English) 
there is a problem. Both month minute and microsecond begin with an "m". To that 
end, all date values are used as lower case letters while all time values are in upper 
case. Microsecond is expressed as MU, which resembles the Greek letter M, the 
scientific notation for the word micro. 



It proves difficult to try to handle all the forms needed in a general manner. "Hd" is 
Hour in Day and is thus 24-houT time. This is not always what is wanted. "Hh" is 
chosen as Hour in Half-day to get the 12-hour form of time. To go along with this 
there is "mi" for Meridiem Indicator. This gives "A" or "P" to make up AM or PM. 
This does not give "AM" or "PM" because ANSI and ISO standards specify that time 
be given as "3P", not "3PM". The users who want the M will just put the literal in, 
i.e. " A miM". 



One other way of looking at a calendar value is in terms of fiscal week. This is 
selected with the " A fw" code. Its value is 4 digits of year followed by 2 digits of 
week number of the year, i.e. "yyyyww". The default format for the A fw code has 
been chosen to give a value of "yww" 
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This table shows the complete set of selectors. The row specifies what unit is wanted, 
the column specifies within what other unit, i.e. A Sy is "Seconds of Year n . 

DATE/TIME SELECTORS 



of 


of 


of 


of 


of 


of 


of 


of 


calen- 


year 


month 


week 


day 


hour 


mi nute 


second 


dar 

















micro- + + + + + + +- 

second | "Uc | "Uy | "Urn | "Uw | "Ud | "UH | "UM | "US | 
+ + + + + + + + + 

second | "Sc | "Sy | "Sm | "Sw | "Sd | ~SH | "SM | 
+ + + + + + + + 

minute | "Mc | "My | "Mm | "rtw | "Md | "MH | 
+ + + + + + + 

hour | "He | "Hy | "Hm | "Hw | "Hd | 
+ + + + + + 

day | "dc | "dy | "dm | "dw | month day zone 
+ + + + + + + + + 

month | | "my | name | "mn | "dn | "zn | 
+ + + + + + + 

year | "yc | abbrev | "ma | "da | "za | 
+ + + + + + 

| "Hh | <-hour of half-day differential | "zd | 

+ + (12 hour form) + + 

| "mi | <-meridiem indicator ("A" or "P") 

+ + 

| "fw j <-f i seal week (form: yyyyww) 

+ + 

| "fi | <-fiscal indicator ("FW" in english) 



The formatting of date and time values can be controlled by an optional PL/I picture 
specification included in the selector. For example, a code of " A 0099yc" formats the 
total years in the calendar value into a 2— digit year of the 20th century. A 9999yc 
provides a full, 4-digit year. The following is a brief description of the most 
frequently-used picture characters. For a more complete discussion of PL/I pictures, 
refer to the Multics PL// Language Specification Manual, Order No. AG94, and the 
Multics PL// Reference Manual, Order No. AM83. 

9 

represents a mandatory decimal digit in the displayed value. 

z 

represents a decimal digit in the displayed value. Nonsignificant zeros on the left 
are replaced by a space when they occupy a "z" digit position. 



produces a period in the displayed value. This has no relation to the location of 
the decimal point in the value actually being displayed. If zero suppression is in 
effect, this is replaced with a space. 
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produces a comma in the displayed value. It has all the characteristics of the 
period. 

v 

locates the value's decimal point in the result This determines how the value 
digits are oriented with respect to the picture specification. If no "v" is given, it 
is assumed to appear after the rightmost picture character. 



The picture characters above are sufficient for displaying most numeric values. For 
example, the control string A 99Hd A 99.v9MH represents the time in hours, minutes and 
tenth of minutes. The control string A zz9.999vUS represents the number of 
milliseconds of the second, using the decimal point and "v" to scale the microsecond 
unit. Scaling can also be performed by a picture scale factor. 

f(N) 

scales the value by multiplying or dividing by a power of 10, thus shifting the 

location of the decimal point in the value. For example, f(2) shifts the decimal 2 

places left, effectively dividing the value by 100. f(-3) shifts 3 places right, 
effectively multiplying by 1000. 

Using a picture scale factor, the milliseconds in excess of a second can be displayed 
to the nearest tenth using the control string 

"zz9-9f (3) US 

A value of 48634 microseconds would be displayed as " 48.6" milliseconds. 

There are 2 extensions to numeric picture handling which can be used in time format 
selectors. 

Z 

represents a decimal digit in the displayed value. Nonsignificant zeros to the left 
of the decimal point are omitted from the displayed value when they occupy a 
"Z" digit position. Nonsignificant zeros to the right of the decimal point are 
omitted from the displayed value when they occupy a "Z" digit position. 

"Z" characters must appear as the leftmost or rightmost digit positions in the 
picture specification, since these are the positions which nonsignificant zeros can 
occupy. "Z" performs a selective Itrim or rtrim (of zero) operation on the 
displayed value. For example, our millisecond specification given above could be 
specified as A ZZ9.9ZZUS without using a picture scale factor. With this specifica- 
tion, 48630 microseconds would be displayed as "48.63" milliseconds (without the 
leading space or trailing zero). 
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O 

represents a decimal digit in the displayed value that should be omitted. 
Specifying A 99yc for a year like 1941 will result in a size condition, since it takes 
4 digits to handle that number. To get the year in century, you may use 
A 0099yc. This gives 4 digits into which the value is placed and then the first 2 
digits are discarded. Note that a picture like OOz9 with a value of 1502 will give 
"02" because the zero-suppression applies to the 1502 and then the first 2 digits 
are dropped. 

Character date/ time values such as day of the week, month name, and time zone can 
be formatted using a character picture specification with the "x" picture character. 

x 

represents a position which may contain any character. Since national characters 
occur in some of the time names, the use of the "a" character should be avoided. 
Values are left- justified in the picture specification, with truncation of the 
rightmost characters if the value is longer than the picture, or padding with 
spaces on the right if the value is shorter than the picture. 

For example, A xxxxxxxxdn displays Wednesday as "Wednesday" and Monday as 
"Monday ". A picture repetition factor can be used to shorten the control string to 
" A (9)xdw". With A (5)xmn, January is displayed as "Janua" and May is displayed as 
"May ". Remember that in some languages, the abbreviation of a time name is not 
the first three letters of it. 

The selector picture specification allows an extension of the "x" picture specification. 
X 

represents an optional character position in the displayed value. The character 
position is omitted if there is no corresponding character in the value being 
displayed. 

"X" characters must appear as the rightmost character positions in the picture 
specification, since this is the position in which nonsignificant spaces can occupy. 
"X" performs a selective rtrim operation on the displayed value. 

The code A (9)Xdw displays Wednesday and Monday both without trailing spaces. 

This table shows the default picture specifications for all selectors. The row specifies 
what unit is wanted, the column specifies within what other unit, i.e. A Sy is "Seconds 
of Year". 
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Examples: The following table shows how date and times strings are displayed by a 
variety of control strinp. 

CONTROL STRING 

"DISPLAYED VALUE" 
A mn "29dm, "9999yc 

"September 8, 1979" 
A mn "z9dm, "9999yc 

"September 8, 1979" 
"dm "ma ~9999yc "zn 

"08 Sep 1979 Mountain Standard Time" 
"my/"dm/"yc "Hd"99v.9MH "za "da 

"09/08/79 0242.4 mst Sat" 
"Hd:"MH:"SM"zd 

"02:42:25-0700" 
"9999yc-"my-"dm__"Hd : "MH : "99 . (6) 9UM_"za_"da 

" 1 979-09"08_02 : 42 : 25 .048634_ms t_Sat" 
<-"<mu 1 1 i cs_t i me>xyz"<mu 1 1 i cs_da te>-> 

"<-02 : 42xyz09/08/79->" 
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Entry: date time Sforniat max length 

This entry returns the length of the longest result which a format can generate. The 
zone and/or language in which to work may be specified. 

USAGE 

declare date time_$ forma t_max_ length entry (char (*) , char (>'«) , char(*)) 
returns (fixed bin) ; 

max_len = date_t i me_$f ormat_max_l ength (format, zone, lang); 

ARGUMENTS 

format 

a control string intended to be given to date_time_$f ormaL (Input) b..argx zone 
the short name of the zone in which conversion will be done. (Input) 
"system_zone" means use the system default zone. "" means use the per-process 
default zone, (input) 

lang 

the language in which month names and time zones are expressed. "system_lang" 
means use the system default time language. "" means use per-process default 
time language. 

max_len 

is the length of the longest string which can result from processing the given 
format. (Output) 

ERROR HANDLING 

The sub_err_ mechanism is used when an error occurs. The inofrmation in the 
sub_error_info structure is explicit as to the type of error and detailed in its 
explanation. Within a sub_error_handler it is easy to display this data. Then a 
message will be produced by: 

call com_err_ (sub_error_i nf o.status_code, "my_name", ""a", 
sub_error_i nf o. i nf o_str i ng) ; 

An example of a detailed message that could result from this: 

my_name: The picture contains a syntax error. 

Format is: "~yc-~98my-~99dm" 
error at: ~ 

See the list under date_time_$format for the values that can be present in the 
status_code field. 
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Entry: date time Sfrom clock 

Given a Multics standard calendar clock value and an output time zone name, return 
the month, day of the month, the year, the hour of the day, the minute of the hour, 
the second of the minute, the number of microseconds, the day in week, the day in 
year, and the day in clock. The caller may specify one of the time zones in the 
time_info_ in which the decoded clock value is to be expressed, or may request that 
the value be expressed in one of the default time zones. 

USAGE 

declare date_t ime_$f rom_clock entry (fixed bin (71), char (*) , ptr, fixed 
bin (35)); 

call date_t ime_$f rom_dock_ (clock, zone, addr (time_va1ue) , code); 

ARGUMENTS 

clock 

is the binary clock value to be decoded. (Input) 

zone 

the short name of the zone in which output time value is expressed. (Input) 
"system_zone" means use the system default zone. means use the per-process 
default zone. 

time_value 

is the structure containing time parts. (Output) See "Structure" below. 

code 

is a standard status code. (Output) It can have one of the following values — 

error_table_$dt_date_too_big 

the date given is after 9999-12-31_23:59:59.999999_GMT. 

error_table_$dt_date_too_small 

the date given is before 0001-01-01_00:00:00.000000_GMT. 

error_tab!e_$dt_year_too_big 

the clock value given, when converted to the specified time zone, is after the 
year 9999. 

error_table_$dt_year_too_small 

the clock value given, when converted to the specified time zone, is before 
the year 0001. 

error_table_$unimplemented_version 

a structure is not a version this procedure can handle. 
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error_table_$unknown_zone 

the time zone specified by the caller was not found in time_info_. 

STRUCTURE 

This is the structure used by date_time_$from_clock to return the parts of a clock 
value. It is also used by date_time_$to_clock to hold the input values which are to be 
combined to make a clock value. This structure is declared in time_value.incl.pll. 



del 1 time value 


aligned based (Ptime value), 


2 


vers ion 


char 


(8), 


2 


yc 


f i xed 


bin, 


2 


my 


f ixed 


bin, 


2 


dm 


f i xed 


bin, 


2 


Hd 


f ixed 


bin, 


2 


MH 


f ixed 


bin, 


2 


SM 


f ixed 


bin, 


2 


US 


f ixed 


bin (20) , 


2 


fw 


f ixed 


bin (20) , 


2 


dw 


f i xed 


bin, 


2 


dy 


f i xed 


bin, 


2 


dc 


f i xed 


bin (22) , 


2 


Uc 


f ixed 


bin(70 , 


2 


za 


char 


(5), 


2 


zone_i ndex 


f i xed 


bin, 


2 


1 eap_year 


f i xed 


bin; 



STRUCTURE ELEMENTS 



version 

Version of this structure (Vtime_value_3). 

yc 

Year part of date (e.g. 1978). All values in this structure are time zone adjusted. 

my 

Month part of date (e.g. 7= July) 

dm 

Day of month part of date (e.g. 4) 

Hd 

Hour of the day (e.g. 18) 

MH 

Minute of the hour (e.g. 35) 

SM 

Second of the minute (e.g. 59) 
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US 

Microseconds in excess of second 

fw 

Fiscal week (a number representing yyyyww) 

dw 

Day of the week (l=Mon, 7=Sun). 

dy 

Day of the year (e.g. 12/31 = 365 or 366). 

dc 

Number of days in calendar value (e.g. Jan 1, 0001 => 1). 

Uc 

Number of microseconds in calendar value (e.g. Jan 1, 0001 midnight => 0). 

za 

The name of the zone in which the data is expressed. 
zone_index 

The index in time_info_$zone_names of the zone. 
leap_year 

This is a 1 if it is a leap year, otherwise it is a 0. 

"date" For date_time_$to_clock fields of the structure are only valid in certain 
combinations. This table shows with the *'s which fields may be present together. 
All others must be zero. 

CASE 



2 -+-3 -+-!♦-+ 



t i me_va 1 
t i me_va 1 
t i me__va 1 
t i me_va 1 
t i me_va 1 
t i me_va 1 
time val 



ue.yc 
ue.my 
ue .dm 
ue. fw 
ue.dw 
ue.dy 
ue.dc 



* 


* 














* 










i'e 


(*) 





In cases 1, 2, & k, i f dw is 
present, it is used to verify 
the value converted. 

In case 3 it actually defines 
a day. If not present, Monday 
is assumed. 



H — v — h-v-H — V-H — V — I- 

| +-clock date ■ converted 
+--- 



(dc) 



clock_date = converted (fw,dw) 
clock_date = converted (yc.dy) 
clock_date = converted (yc,my,dm) 



2-198 



AG93-05 



date time 



date time 



Entry: date time $from clock interval 

Given two clock values, return the number of years, months, weeks, days, hours, 
minutes, seconds, and microseconds between them. The set of units to use is specified, 
as well as whether any are to include the fractional remainder. 

USAGE 

declare date_t ime_$f rom_clock_i nterval entry (fixed bin(71)» fixed 
bin (71), ptr, fixed bin (35)); 

call date_t ime_$from_c 1 ock_i nterval (clockl, clock2, addr 
(t ime_of f sets) , code) ; 

ARGUMENTS 

clockl 

is the base time value. (Input) The output is expressed relative to this binary 
clock value. 

clock2 

is the offset time value. (Input) clockl is in essence subtracted from this value. 
If this value is later than clockl, all results will be positive. If this value is 
earlier, all results will be negative. 

time_offsets 

is the structure containing resulting time values. (Output) See "Notes" below. 

code 

is a standard status code. (Output) It can have one of the following values — 

error_table_$dt_bad_day_of_week 

the returned clock reading does not fall on the given day of the week. 

error_table_$dt_bad_dm 

day_in_month<l or day_in_month>month_size. 

error_table_$dt_bad_dy 

day_in_year < 0 or day_in_year > year_size (which is 355 for 1582). 

error_table_$dt_bad_my 

month_in_year<l or month_in_year>12. 

error_table_$dt_date_not_exist 

the date given is in the nonexistent range of 1582-10-05 through 1582-10-14 

error_table_$dt_date_too_big 

the date given is after 9999-12-31_23:59:59.999999_GMT. 
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error_table_$dt_date_too_small 

the date given is before 0001-01-01_00:00:00.000000_GMT. 

error_table_$dt_no_interval_units 

no units given in which to express the interval. 

error_table_$dt_of f set_too_big_negati ve 

an offset is so big that when it is applied, it yields a date before 
0001-01-01 J)0:00:00.000000_GMT. 

error_table_$dt_of f set_too_big_positi ve 

a negative offset is so big that when it is applied, it yields a date after 
9999-12-31_23:59:59.999999_GMT. 

error_table_$dt_year_too_big 

the clock value given, when converted to the specified time zone, is after the 
year 9999. 

error_table_$dt_year_too_small 

the clock value given, when converted to the specified time zone, is before 
the year 0001. 

error_table_$unimplemented_version 

a structure is not a version this procedure can handle. 

NOTES 

The following structure is used by both date_time_$from_clock_interval and 
date_time_$offset_to_clock. For from_clock_interval, it contains all of the offset 
values which define the indicated interval. For offset „to_ clock, it contains all the 
values to be added to clock value. This structure is declared in time_offset.incl.pll. 
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del 1 t ime_of f set aligned based (Pt ime_of f set) , 



vers ion 


char 


(8) , 




flag, 








3 yr 


f i xed 


bin, 




3 mo 


f i xed 


bin, 




3 wk 


f i xed 


bin, 




3 da 


f ixed 


bin, 




3 hr 


f ixed 


bin, 




3 min 


f i xed 


bin, 




3 sec 


f i xed 


bin, 




3 Usee 


f i xed 


bin, 




val , 








3 yr 


float 


dec 


(20), 


3 mo 


float 


dec 


(20), 




float 


dec 


(20), 


3 da 


float 


dec 


(20) , 


3 hr 


float 


dec 


(20), 


3 min 


float 


dec 


(20), 


3 sec 


float 


dec 


(20), 


3 Usee 


float 


dec 


(20), 


dw, 








3 flag 


f i xed 


bin, 




3 val 


f i xed 


bin; 





STRUCTURE ELEMENTS 
version 

Version of this structure (Vtime_offset_2). 



For from_clock_interval, this structure specifies which units are to be used to 
express the interval. For offset_to_clock, it specifies which fields contain data to 
be used. These fields may contain one of 3 values. The meaning depends on 
which operation is being done. 

UNUSED (=0) 

the corresponding time_offset.val units are not used. 

USED (=1) 

For offset_to_clock, the corresponding time_offset.val unit is applied as an 
offset. 

INTEGER (=1) 

For from_clock_interval, an integer value is returned in the corresponding 
time_offset.val units field. 

FRACTION (=2) 

For from_clock_interval, the corresponding time_offset.val units field is 
returned as a real number of units (including fractional units). 
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The fields in this sub-structure represent years, months, weeks, days, hours, 
minutes, seconds, and microseconds. 

val 

The fields in this sub-structure contain the various values. For offset_to_clock 
they are the values to be added to the clock. They may be negative if need be. 
For from_clock_interval they are the values which made up the indicated interval. 
Each of these fields is in use only if its flag is set. These fields are named just 
like the flags are. 

dw.flag 

specifies how a day of week adjustment is to be applied by offset_to_clock. 
When applying a day of week offset, the day of week given in dw.val will be 
used as an offset from the given clock_in value. It must have one of the 
following values, which may be referred to using the named constants: 

BEFORE (=2) 

select the date before clock_in on which the specified day of week most 
recently occurred, 

ON_OR_BEFORE (=-1) 

select the date on or before clock_in on which the specified day of week 
most recently occurred. 

UNUSED (=0) 

do not apply a day of week offset 

ON_OR_ AFTER (=1) 

select the date on or after clock_in on which the specified day of week will 
next occur. 

AFTER (=2) 

select the date after clock_on on which the specified day of week will next 
occur. 

dw. value 

specifies a day of week to be used as an offset. It may range from +1 to +7, 
where 1 = Monday, ... and 7 = Sunday. 

Entry: date time $fstime 

This entry performs the same function as date_time_ given a 36-bit storage system 
date value. 

USAGE 

declare date_t ime_$f stime entry (bit (3d) aligned, char(*)); 
call date time_$fstime (ssclock, str) ; 
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ARGUMENTS 
ssclock 

is an internal storage system clock value. (Input) 

str 

is the resultant character string. (Output) 



Entry: date time Soffset to clock 

This entry point creates a new Multics clock value by adjusting an input clock value 
to a specified day-of-week and then adding relative date/ time offsets. The relative 
date/ time values include a year offset, month offset, week offset, day offset, hour 
offset, minute offset, second offset, and microsecond offset. Any of these values may 
be zero (no offset from input clock value) or negative (backwards offset from input 
clock value). In addition, an input time zone is specified. 

USAGE 

declare date_t ime_$of f set_to_clock entry (ptr, fixed bin (71), char (*) , 
fixed bin (71), fixed bin (35)); 

call date_t ime_$of f set_to_c 1 ock (addr (t ime_of f set) , clock_in, zone, 
clock, code) ; 

ARGUMENTS 

time_offset 

is the structure containing time offsets to be applied. (Input) Structure is defined 
in time_offset.incl.pll. 

clock_in 

is the clock value to which offsets are applied. (Input) 

zone 

is the zone in which clock_in is to be interpreted. (Input) 
clock 

is the resulting clock value. (Output) 

code 

is a standard status code. (Output) It can have one of the following values — 



error_table_$dt_bad_day_of_week 

the returned clock reading does not fall on the given day of the week. 

error_table_$dt_bad_dm 

day_in_month<l or day_in_month>month_size. 
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error_table_$dt_bad_dy 

day_in_year < 0 or day_in_year > year_size (which is 355 for 1582). 

error_table_$dt_bad_my 

month_in_year<l or month_in_year>12. 

error_table_$dt_date_not_exist 

the date given is in the nonexistent range of 1582-10-05 through 1582-10-14 

error_table_$dt_date_too_big 

the date given is after 9999-12-3 1.23:59:59. 999999_GMT. 

error_table_$dt_date_too_small 

the date given is before 0001-01-01_00:00:00.000000_GMT. 

error_table_$dt_of f set_too_big_negati ve 

an offset is so big that when it is applied, it yields a date before 
0001-01-01_00:00:00.000000_GMT. 

error_table_$d t_of f set_too_b!g_positi ve 

a negative offset is so big that when it is applied, it yields a date after 
9999-12-31_23:59:59.999999_GMT. 

error_table_$dt_year_too_big 

the clock value given, when converted to the specified time zone, is after the 
year 9999. 

error_table_$dt_year_too_small 

the clock value given, when converted to the specified time zone, is before 
the year 0001. 

error_table_$unimplemented_version 

a structure is not a version this procedure can handle. 

NOTES 

See the notes under date_time_$from_clock_interval for the description of the 
time_offset structure. The order of applying these offsets can affect the resultant 
clock value. In all cases, the order required by convert_date_to_binary_ has been used. 
The order is as follows: 

1) decode the input clock value into absolute date/ time values specified in terms of 
the input time zone. This zone may affect the day-of-week represented by the 
input clock value, and hence, may affect any day-of-week offset adjustment. 

2) apply any day-of-week offset by adding/subtracting days to/from the absolute 
date until the day-of-week represented by the decoded clock value equals the 
specified day-of-week. 



2-204 



AG93-05 



date_time_ 



date_time_ 



3) apply any year offset to the decoded clock value. If applying the year offset 
results in a nonexistent date, then use the previous existing day, e.g. "1583-10-10 
-lyr" would yield 1582-10-04. 

4) apply any month offset to the decoded clock value. If applying the month offset 
results in a nonexistent date, then use the last day of the month (taking leap 
years into account), e.g. "Jan 31 3 months" would yield April 30. instead. 

5) apply the day offset, hour offset, minute offset, second offset, and microsecond 
offset 

6) encode the resultant absolute date/ time specification into the output clock value. 
Entry: date time_$set lang 

This entry sets or resets the user's default time language. 
USAGE 

declare date_time_$set_lang (char (*) , fixed bin (35)); 

call date_t ime_$set_l ang (lang, code); 

ARGUMENTS 

lang 

the language which is to be made current. (Input) "system_lang" means use the 
system default time language. 

code 

is a standard status code. (Output) It can have one of the following values — 



error_table_$dt_unknown_time_language 

the language specified by the caller was not found in time_info_. 

Entry: date time $set zone 

This entry sets or resets the user's default zone. 
USAGE 

declare date_t ime_$set_zone entry (char (*) , fixed bin(35))» 
call date_time $set zone (zone code); 
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ARGUMENTS 
zone 

the short name of the zone which is to be made current. (Input) "system_zone" 
means use the system default zone. 

code 

is a standard status code. (Output) It can have the following value: 



error_table_$unknown_zone 

the time zone specified by the caller was not found in time_info_. 



Entry: date time $to clock 

Given any or all of the following - years, months, days, hours, minutes, seconds, 
microseconds, day in week, day in year, or day in clock - returns a standard clock 
value which represents the encoding of these values. All the values must be valid, i.e. 
net greater than 23, etc. 

USAGE 

declare date_time_$to_clock (ptr, fixed bin (71). fixed bin (35)); 
call date_t ime_$to_c 1 ock (addr (time_value) , clock, code); 
ARGUMENTS 
time_value 

is the structure containing time parts. (Input) The structure is defined in 
time_value.incl.pll. 

clock 

is the encoded clock value. (Output) 

code 

is a standard status code. (Output) It can have one of the following values — 



error_table_$bad_time 

the time represented by hour, minute and second is invalid, e.g. 23:60 or 
negative time values 

error_table_$dt_bad_day_of_week 

the returned clock reading does not fall on the given day of the week. 

error_tab!e_$dt_bad_dm 

day_in_month<l or day_in_month>month_size. 
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error_table_$dt_bad_dy 

day_in_year < 0 or day_in_year > year_size (which is 355 for 1582). 

error_table_$dt_bad_my 

month_in_year<l or month_in_year>12. 

error_table_$dt_conflict 

there is a conflicting combination of day-in-calendar, day-in-year, month-in-year, 
day-in-month and fiscal-week. 

error_table_$dt_date_not_exist 

the date given is in the nonexistent range of 1582-10-05 through 1582-10-14 

error_table_$dt_date_too_big 

the date given is after 9999-12-31_23:59:59.999999_GMT. 

error_table_$dt_date_too_small 

the date given is before 0001-01-01_00:00:00.000000_GMT. 

error_table_$unimplemented_version 

a structure is not a version this procedure can handle. 

error_table_$unknown_zone 

the time zone specified by the caller was not found in time_info_. 

NOTES 

See the notes under date_time_$from_clock for the description of the time_value 
structure. 



Entry: date_time_$valid format 

This entry checks the validity of a format string using precisely the same tests as 
date_time_$f ormat 

USAGE 

declare da te_t ime_$val id__f ormat (char (*) , fixed bin, fixed bin(35))» 

call date_t ime_$va1 id_f ormat (format, errloc, code); 

ARGUMENTS 

format 

either a keyword, or an ioa-like control string describing the desired result in 
terms of literal characters and date/ time selectors. (Input) See the date_time_$f ormat 
entry point for a description of valid format strings. 
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errloc 

is the character index in the format string where the error occurred. (Output) 
This is meaningful only if it and code are both nonzero. 

code 

is a standard status code. (Output) It can have one of the following values — 

error_table_$dt_bad_f ormat_selector 

unrecognized selector in format string. 

error_table_$bad_conversion 

a conversion condition occurred while trying to convert a value. 

error_table_$dt_no_f ormat_selector 

the format string contains no selectors and is not a known keyword. 

error_table_$picture_bad 

the picture supplied is in error. 

error_table_$picture_scale 

the picture scale factor not in the range -128:+127. 

error_table_$picture_too_big 

the normalized picture exceeds 64 characters. 

error_table_$size_error 

the size condition occurred during processing. 

error_table_$unimplemented_version 

a structure is not a version this procedure can handle. 



Name: datebin 

The datebin_ subroutine has several entry points to convert clock readings into binary 
integers (and vice versa) representing the year, month, day, hour, minute, second, 
current shift, day of the week, number of days since January 1, 1901, and the number 
of days since January 1 of the year indicated by the clock. Clock readings are 
Multics Greenwich mean time (GMT); all other arguments represent local time. 

If arguments passed to datebin_ are not in the valid range, the returned arguments are 
generally 0 (in certain cases, no checking should be done). 
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Entry: datebin_$clockathr 

This entry point returns a clock reading for the next time the given hour occurs. 
USAGE 

declare datebi n__$clockathr entry (fixed bin, fixed b i n (7 1 ) ) ; 

call datebi n_$clockathr (22, clock); 

ARGUMENTS 

zz 

is the desired hour and minutes expressed as hhmm in decimal (e.g., 1351). 
(Input) 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Output) 



Entry: datebin_$datebin 

This entry point returns the month, day, year, hour, minute, second, weekday, shift, 
and number of days' since January 1, 1901, given a calendar clock reading. 

USAGE 

declare datebi n_ entry (fixed bin (71) > fixed bin, fixed bin, fixed bin, 
fixed bin, fixed bin, fixed bin, fixed bin, fixed bin, fixed bin); 

call datebin_ (clock, absda, mo, da, yr, hr, min, sec, wkday, s) ; 

ARGUMENTS 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Input) 

absda 

is the number of the days the clock reading represents (with January 1, 1901 = 
1). (Output) 

mo 

is the month (1-12). (Output) 

da 

is the day of the month (1-31). (Output) 
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yr 

is the year (1901-1999). (Output) 

hr 

is the hour of the day (0-23). (Output) 

min 

is the minute of the hour (0-59). (Output) 

sec 

is the second of the minute (0-59). (Output) 
wkday 

is the day of the week (1 = Monday, 7 - Sunday). (Output) 

s 

is the shift, as defined in installation_parms. (Output) 



Entry: datebin__„$datofirst 

This entry point returns the number of days since January i, 1901, up to but not 
including January 1 of the year specified. 

USAGE 

declare dateb i n_$datof i rst entry (fixed bin, fixed bin); 

call datebi n_$datof i rst (yr, datofirst); 

ARGUMENTS 

yr 

is the year (1901-1999). (Input) 
datofirst 

is the number of days since January 1, 1901, up to, but not including, January 1 
of the year specified. (Output) 



Entry: datebin Sdayr elk 

This entry point returns the day of the year (1-366) given a calendar clock reading. 
If clock is invalid, -1 is returned. 

USAGE 

declare dateb i n_$dayr__c 1 k entry (fixed bi n (71) * fixed bin); 
call dateb in_$dayr_c Ik (clock, dayr) ; 
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ARGUMENTS 
clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Input) 

dayr 

is the day of the year (1-366). (Output) 



Entry: datebin $dayr_mo 

This entry point returns the day of the year when given a month, day, and year. 
USAGE 

declare dateb i n_$dayr_mo entry (fixed bin, fixed bin, fixed bin, 
f i xed bin); 

call dateb i n_$dayr_mo (mo, da, yr, dayr); 

ARGUMENTS 

mo 

is the month (1-12). (Input) 

da 

is the day of the month (1-31). (Input) 

yr 

is the year (1901-1999). (Input) 

dayr 

is the day of the year (1-366). (Output) 



Entry: datebin Sfollowing midnight 

This entry point, given a clock reading, returns a clock reading for midnight (local 
time) of that day. 

USAGE 

declare datebin $fol lowing midnight entry (fixed bi n (7 1) » 
fixed bin (7D) ; 

call datebi n_$fol lowi ng_midnight (oldclock, clock); 
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ARGUMENTS 
oldclock 

is a calendar clock reading in microseconds since January 1, 1901, 0000 GMT. 
(Input) 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Output) 



Entry: datebin $last midnight 

This entry point returns a clock reading for the midnight (local time) preceding the 
current day. 

USAGE 

declare datebin_$last_midnight entry (fixed bin(7D); 

call datebi n_$ last_midnight (clock); 

ARGUMENTS 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Output) 



Entry: datebin Snext shift change 

This entry, given a clock reading, returns the time of the next shift change, the 
current shift, and the new shift. 

USAGE 

declare datebi n_$next_shi ft_change entry (fixed bin(70» fixed bi n (71) • 
fixed bin, fixed bin) ; 

call datebin_$next_shif t_change (clock, newclock, shift, newshift); 

ARGUMENTS 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Input) 

newclock 

is the time the shift changes next after clock. (Output) 
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shift 

is the current shift at time clock. (Output) 
newshift 

is the shift that begins at time newclock. (Output) 



Entry: datebin_3preceding_jnidnight 

This entry point, given a clock reading, returns a clock reading for midnight (local 
time) of the preceding day. 

USAGE 

declare datebin_$preceding_midnight entry (fixed bi n (7 1) • 
fixed bin(7D) ; 

call datebin_$preceding_midnight (oldclock, clock); 

ARGUMENTS 

oldclock 

is a calendar clock reading in microseconds since January 1, 1901, 0000 GMT. 
(Input) 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Output) 



Entry: datebin Srevert 

This entry point returns a calendar clock reading for the month, day, year, hour, 
minute, and second specified. 

USAGE 

declare dateb i n_$revert entry (fixed bin, fixed bin, fixed bin, 
fixed bin, fixed bin, fixed bin, fixed bi n (71) ) ; 

call datebin_$revert (mo, da, yr, hr, min, sec, clock); 

ARGUMENTS 

mo 

is the month (1-12). (Input) 

da 

is the day of the month (1-31). (Input) 
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yr 

is the year (1901-1999). (Input) 

hr 

is the hour of the day (0-23). (Input) 

min 

is the minute of the hour (0-59). (Input) 

sec 

is the second of the minute (0-59). (Input) 
clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Output) 



Entry: datebin $revertabs 

This entry point returns a calendar clock reading given the number of days since 
January 1, 1901. 

USAGE 

declare da teb i n_$r ever tabs entry (fixed bin, fixed b i n (7 1 ) ) ; 

call datebi n_$revertabs (absda, clock); 

ARGUMENTS 

is the number of the days the clock reading represents (with January 1, 1901 - 
1). (Input) 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Output) 



Entry: datebin Sshift 

This entry point returns the shift given a calendar clock reading. If clock is invalid, 
-1 is returned. 

USAGE 

declare dateb i n_$sh i f t (fixed b i n (7 1) » fixed bin); 
call datebin $shift (clock, s) ; 
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ARGUMENTS 
clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Input) 

s 

is the shift, as defined in installation_parms. (Output) 



Entry: datebin__$this_midnight 

This entry point returns a clock reading for midnight (local time) of the current day. 
USAGE 

declare datebi n_$thi sjnidni ght entry (fixed b i n (7 1) ) ; 

call datebi n_$this_m idni ght (clock); 

ARGUMENTS 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Output) 



Entry: datebin $time 

This entry point returns the hour, minute and second given a calendar clock reading. 
If clock is invalid, hr, min, and sec are -1. 

USAGE 

declare datebi n_$time entry (fixed bin(7D» fixed bin, fixed bin, 
f i xed bin); 

call datebin_$time (clock, hr, min, sec); 

ARGUMENTS 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Input) 

hr 

is the hour' of the day (0-23). (Output) 

min 

is the minute of the hour (0-59). (Output) 
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sec 

is the second of the minute (0-59). (Output) 
Entry: datebin Swkday 

This entry point returns the day of the week (Monday - 1 ... Sunday = 7) given a 
calendar clock reading. If clock is invalid, 0 is returned. 

USAGE 

declare datebi n_$wkday entry (fixed b i n (71) * fixed bin); 

call datebi n_$wkday (clock, wkday) ; 

ARGUMENTS 

clock 

is a calendar clock reading with the number of microseconds since 0000 GMT 
January 1, 1901. (Input) 

wkday 

is the day of the week (1 = Monday, 7 = Sunday). (Output) 



Name: decode__definition__ 

The decode_definition_ subroutine, given a pointer to an object segment definition, 
returns the decoded information of that definition in a structured, directly accessible 
format This subroutine can only be used on one segment at a time because it uses 
internal static storage. 

USAGE 

declare decode_def ini tion_ entry (ptr, ptr, bit 1 aligned) 
call decode_def ini tion_ (def_ptr, structure__ptr , eof) 
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ARGUMENTS 
def_ptr 

is a pointer to the selected definition. (Input). (The caller extracts this from the 
previously returned information.) The initial pointer with which decode_definition_ 
can be called is a pointer to the base of the object segment (i.e., with a zero 
offset), unless the decode_definition_$init entry point has been called, in which 
case the initial pointer can be a pointer to the beginning of the definition section 
(as returned by the object_info_ subroutine). 

structure_ptr 

is a pointer to the provided structure in which decode_definition_ returns the 
desired information. (Input). (See "Notes" below.) 

eof 

is a binary indicator that is *T'b if the current invocation of decode_definition_ 
causes the search to go beyond the end of the definition list. If that is the case, 
the returned information in the structure is null. It may also be 'T'b if any 
error occurs. (Output) 

NOTES 

The structure, contained in the decode_definition_str.incl.pll structure, has the following 
format: 

del 1 decode_def i n i t ior_commor_header based aligned, 
2 next_def ptr, 
2 prev_def ptr, 
2 block_ptr ptr, 
2 section char (k) aligned, 
2 offset fixed bin, 

2 entrypoint fixed bin; 

del 1 decode_def i n i t ion_str based aligned, 

2 header like decode_def ini t i on_common_header , 

2 symbol char (32) aligned; 

STRUCTURE ELEMENTS 

next_def 

is a forward pointer to the next definition in the list. It can be used to make a 
subsequent call to decode_definition_. 

prev_def 

is a backward pointer to the preceding definition on the list. This pointer can be 
null if the definition is of the old format 
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block_ptr 

is a pointer to the head of the definition block if this is a segname definition 
and to the head of a segname list if this is not a segname definition. This 
pointer can be null if the definition is of the old format 

section 

is a symbolic code defining the type of definition. It can assume one of the 
following values: text, link, stat, symb, or segn (for segname). 

offset 

is the offset of the definition within the given section. This is set to 0 if section 
is segn. 

entrypoint 

is nonzero, if this definition is an entry point. The value of this item is the 
entry point's offset in the text section. 

symbol 

is the character string representation of the definition. 



Entry: decode definition Sdecode cref 

This entry point, given a pointer to an object segment definition, returns the decoded 
information of that definition in a structure similar to that returned by decode_definition_, 
but with a pointer to the symbol name instead the name itself. It is used only by the 
cross_reference command. 

USAGE 

declare decode_def i n i t i on_$decode_cref entry (ptr, ptr, bit (1) aligned, 
ptr) ; 

call decode_def ini tion_$decode_cref (def_ptr, decode_def_acc_ptr , eof, 
1 i nk_ptr) ; 

ARGUMENTS 

def_ptr 

must be a pointer to the beginning of the definition section. (Input) 
decode_def_acc_ptr 

is a pointer to a structure in which the entry point is to return information. 
(Input). (See "Notes" below.) 

eof 

is a binary indicator that is "l"b if the current invocation of decode_def inition_ 
causes the search to go beyond the end of the definition list. If that is the case, 
the returned information in the structure is null. It may also be 'T'b if any 
error occurs. (Input) 
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link_ptr 

is a pointer to the base of the linkage section of the object segment the first 

time this entry is called for a given object segment. It is to be null for 

subsequent calls. (Input) 

NOTES 

The structure filled in by this entry point has the following format. It can be found 
in decode_descriptor_str.incl.pll. 

del 1 decode_def ini tion_acc based aligned, 

2 header like decode_def i ni tion_common_header , 
2 acc_ptr ptr; 

STRUCTURE ELEMENTS 

header 

all items in this substructure are the same as for the decode_definition_str 
substructure header. 

acc_ptr 

is a pointer to the ACC string that is the symbolic name of this definition. 



Entry: decode definition $full 

This entry point, given a pointer to an object segment definition, returns more 
complete information about that definition. The symbolic name returned by this entry 
point can contain up to 256 characters. This entry point does not use internal static 
storage. 

USAGE 

declare decode_def i ni t ion_$f ul 1 entry (ptr, ptr, ptr, bit (1) aligned) 
returns (bit(l) aligned); 

call decode_def ini tion_$ful 1 (def_ptr, structure_ptr , oi_ptr, eof) ; 

ARGUMENTS 

def_ptr 

is a pointer to the selected definition and is extracted from previously returned 
information. (Input). The initial pointer with which the decode_definition_$full 
entry point can be called is a pointer to the base of the definition section of the 
object segment. 

structure_ptr 

is a pointer to the provided structure into which the decode_definition_$full entry 
point returns the desired information. (Input). (See "Notes" below.) 
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oi_ptr 

is a pointer to the structure returned by any entry point of the object_info 
subroutine. (Input) 



is a binary indicator that is "l"b if the current invocation of decode_definition_ 
causes the search to go beyond the end of the definition list. If that is the case, 
the returned information in the structure is null. It may also be "l"b if any 
error occurs. (Output) 



NOTES 



The structure, contained in the decode_definition_str.incl.pll structure, has the following 
format 



del 1 decode_def i ni t ion_f ul 1 based aligned 



2 header 
2 symbol 
2 symbol _1 ng 

c i i wya , 

3 new_format 

3 ignore 

3 entrypt_flag 

3 retain 

3 arg_count 

3 desc_sw 

3 unused 
2 nargs 
2 desc_ptr 



like decode_def i n i t i on_common_header , 
char (256) aligned, 
f i xed bin, 



t 
t 
t 
t 
t 
t 
t 
xed 



unal igned, 
unal igned, 
unal i gned, 
unal igned, 
unal i gned, 
unal i gned, 
30) unal i gned, 
bin, 



ptr ; 



STRUCTURE ELEMENTS 



header 

all items in this substructure are the same as for the decode_definition_str 
substructure header. 



symbol 

is the character string representation of the definition. 
symbol_lng 

is the relevant length of the symbol in characters. 
new_format 

indicates that the definition is in the new format 



ignore 

is the linker ignore switch. 

"l"b the linker should ignore this definition. 

"0"b the linker should not ignore this definition. 
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entrypt_flag 

is the entry point switch. 

"l"b the definition is for an entry point 

"0"b the definition is for a segdef. 

retain 

is the retain switch. 

"l"b the definition should be retained. 
"0"b the definition should not be retained. 

arg_count 

is the arg_count switch. 

"l"b there is an arg_count for this definition. 
"0"b there is no arg_count for this definition. 

desc_sw 

is the descriptor switch. 

"l"b there are descriptors for this definition. 

"0"b there are no descriptor for this definition. 

unused 

is padding. 

nargs 

indicates the number of arguments expected by this entry, if descr_sw equals "l"b. 
desc_ptr 

points to an array of 18-bit pointers to the descriptors for the entry, if descr_sw 
equals "l"b. 



Entry: decode definition $init 

This entry point is used for initialization and is especially useful when the object 
segment does not begin at offset 0 (as for an archive component). This entry point 
has no effect when the decode_definition_$full entry point is being used. 

USAGE 

declare decode_def i n i t i on_$ i n i t entry (ptr, fixed bin (2*0); 
call decode_def ini tion_$init (seg_ptr, bit_eount); 
ARGUMENTS 
seg_ptr 

is a pointer to the beginning of an object segment (not necessarily with an offset 
of 0). (Input) 
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bit_count 

is the bit count of the object segment. (Input) 



Name: decode descriptor 

The decode_descriptor_ subroutine extracts information from argument descriptors. It 
should be called by any procedure wishing to handle variable length or variable type 
argument lists. It processes the descriptor format used by PL/ 1, BASIC, COBOL, 
| FORTRAN, and Pascal. 

USAGE 

declare decode_descr i ptor_ entry (ptr, fixed bin, fixed bin, 
| bit(l) aligned, fixed bin, fixed bin (2*0, fixed bin); 

call decode_descr i ptor_ (ptr, n, type, packed, ndims, size, scale); 

ARGUMENTS 

ptr 

points either directly at the descriptor to be decoded or at the argument list in 
which the descriptor appears. (Input) 

n 

controls which descriptor is decoded. If n is 0, ptr points at the descriptor to be 
decoded; otherwise, ptr points at the argument list header and the nth descriptor 
is decoded. (Input) 

type 

is the data type specified by the descriptor. (Output) 
* -1 is returned if descriptors are not present in the argument list, if the nth 
| descriptor does not exist, or if the descriptor is in an old format 

packed 

describes how the data is stored. (Output) 



"l"b data is packed 
"0"b data is not packed 

* 

ndims 

| indicates the number of dimensions of an array. (Output) 

* N descriptor is an array of N dimensions 
0 descriptor is a scalar 

size 

* is the arithmetic precision, string size, or number of structure elements. (Output) 
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scale 

is the scale of an arithmetic value. (Output) 



Name: define area 

The define_area_ subroutine is used to initialize a region of storage as an area and to 
enable special area management features as well. The region being initialized may or 
may not consist of an entire segment or may not even be specified at all, in which 
case a segment is acquired (from the free pool of temporary segments) for the caller. 

See the release_area_ subroutine for a description of how to free up segments 
acquired via this interface. 

USAGE 

declare define_area_ entry (ptr, fixed bin (35)); 
call define_area_ (info_ptr, code); 
ARGUMENTS 
info_ptr 

points to the information structure described in "Notes" below. (Input) 

code 

is a system status code. (Output) 
NOTES 

The define_area_ subroutine gives the user more control over an area than is defined 
in the PL/ 1 language. The PL/ 1 empty built-in function cannot empty a define_area_ 
area; the release_area_ subroutine must be used instead. PL /I offset values and PL /I 
area assignment cannot be used with extensible areas. In PL/ 1, an area variable is 
always initialized. Consequently, if a based area is overlayed upon arbitrary storage 
instead of being allocated with a PL/ 1 allocate statement, then the define_area_ 
subroutine must be used to turn the contents of the based area into a PL/ 1 area 
value. 

The structure pointed to by info_ptr is the standard area_info structure used by the 
various area management routines and is described by the following PL/ 1 declaration 
defined by the system include file, area_info.incl.pll: 
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del 1 area_info 

2 version 

2 control , 
3 extend 
3 zero_on_al loc 
3 zero_on_free 
3 dont_free 
3 no_freeing 
3 system 
3 pad 

2 owner 

2 n_components 
2 size 

2 version_of_area 
2 areap 

2 all ocated_b 1 ocks 
2 free_blocks 
2 al located_words 
2 free_words 

STRUCTURE ELEMENTS 



al i gned based, 
fixed bin, 

bi t (1) unal igned, 
b i t (1) unal i gned , 
bi t (1) unal igned, 
b i t (1) unal i gned , 
bit(l) unaligned, 
b i t (1) unal i gned, 
bit (30) unal i gned, 
char (32) unaligned, 
fixed bin, 
f ixed bin (30) , 
fixed bin, 
ptr , 

fixed bin, 
fixed bin, 
fixed bin (30) , 
f ixed bin (30) ; 



version 

is to be filled in by the caller and should be 1. 
control 

are control flags for enabling or disabling features of the area management 
mechanism. 

extend 

indicates whether the area is extensible. This feature should only be used for 
per-process, temporary areas. 
"l"b yes 
"0"b no 

zero_on_alloc 

indicates whether blocks are cleared (set to all zeros) at allocation time. 
"l"b yes 
"0"b no 

zero_on_free 

indicates whether blocks are cleared (set to all zeros) at free time. 
"l"b yes 
"0"b no 

dont_free 

indicates whether the free requests are disabled, thereby not allowing reuse of 
storage within the area. 
"l"b yes 
"0"b no 
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no_freeing 

indicates whether the allocation method assumes no free requests will ever be 
made for the area and that, hence, a faster allocation strategy can be used. 
"l"b yes 
"0"b no 

system 

causes the use of hcs_$make_seg instead of get_temp_segments to create the first 
component. It assumes that the original area is all zeroes, rather than explicitly 
zeroing it 
"l"b yes 
"0"b no 

pad 

is not used and must be all zeros, 
owner 

is the name of the program requesting that the area be defined. This is needed 
by the temporary segment manager. 

n_components 

is the number of components in the area. (This item is not used by the 
define_area_ subroutine.) 

size 

is the size, in words, of the area being defined. The minimum size is thirty-two 
(decimal) words. The maximum size is the maximum number of words in a 
segment. 

version_of_area 

is 1 for current areas and 0 for old-style areas. (This item is not used by the 
define_area_ subroutine.) 

areap 

is a pointer to the region to be initialized as an area. If this pointer is null, a 
temporary segment is acquired for the area and areap is set as a returned value. 
If areap is initially nonnull, it must point to a 0 mod 2 address. 

allocated_blocks 

is the number of allocated blocks in the entire area. (This item is not used by 
the define_area_ subroutine.) 

free_b!ocks 

is the number of free blocks in the entire area (not counting virgin storage). 
(This item is not used by the define_area_ subroutine.) 

allocated_words 

is the number of allocated words in the entire area. (This item is not used by 
the define_area_ subroutine.) 
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free_words 

is the number of free words in the entire area. (This item is not used by the 
define_area_ subroutine.) 



Name: delete 

The delete, subroutine deletes segments, directories, multisegment files, and data 
management files and unlinks links. If the segment, directory, multisegment file or 
data management file to be deleted is protected (i.e„ the safety switch or copy switch 
is on), the subroutine requires user verification before attempting to remove the 
protection. There are two entry points: one called with a pathname, the other with a 
pointer to a segment. Both have a set of switches that specify the actions to be taken 
by the subroutine. If the specified entry is a segment, it is terminated using the 
term_ subroutine. In general, users should call the delete, subroutine rather than 
directly addressing entry points in hcs_. If a data management file is subject to a 
pending transaction, the data management file can not be deleted until the transaction 
is completed. 



Entry: delete Spath 

This entry point is called with the pathname of the segment, directory, multisegment 
file, data management file, or link to be deleted. 

USAGE 

declare delete Spath entry (char (*) , char (*) , bit (6), char (*) , 

fixed bin (35) ) ; 

call delete_$path (dir_name, entryname, switches, caller, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
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entryname 

is the entryname of the segment, directory, multisegment file, data management 
file, or link. (Input) 

switches 

are six switches that specify the actions to be taken. (Input) The switches must 
be given in the order listed below. 
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force_sw 

'T'b allows the entry to be deleted even if it is protected. 
"0"b acts according to question_sw if the entry is protected. 

question_sw 

'T'b asks the user if a protected entry should be deleted if the force_sw is 
"0"b; if the user gives a negative response, the subroutine returns the 
code error_table_$action_not_performed. If question_sw is 'T'b and 
the entryname argument is the name of a directory, the delete_ 
subroutine prints an error message for the first entry under the 
directory that cannot be deleted. 

"0"b deletes the entry without interrogating the user; if unable to delete the 
entry, the subroutine returns an appropriate storage system status code. 

The following switches allow control by the caller over which storage system entry 
types can be deleted: 

directory_sw 

'T'b allow the entryname argument to refer to a directory. 
"0"b return the code error_table_$dirseg if the entryname argument refers to 
a directory. 

segment_sw 

'T'b allow the entryname argument to refer to a segment, multisegment file, 

or data management file. 
"0"b return the code error_table_$nondirseg if the entryname argument refers 

to a segment on a multisegment file. 

link_sw 

'T'b allow the entryname argument to refer to a link (see chase_sw). 
"0"b return the code error_table_$not_a_branch if the entryname argument 
refers to a link. 

chase_sw 

'T'b allow the target of a link to be deleted, if link_sw = 'T'b and the 
entryname argument refers to a link; the deletion of the segment or 
directory pointed to by the link is governed by the settings of 
directory_sw and segment_sw. 

"0"b unlink the link if link_sw ="l"b and the entryname argument refers to 
a link. 

caller 

is the name of the calling procedure, to be used when questions are asked. 
(Input) 

code 

is a storage system status code. (Output) 
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Entry. delete_$ptr 

The delete_$ptr entry point is similar to the delete_$path entry point, except that the 
caller has a pointer to the actual segment to be deleted. Directories, multisegment 
files, Data Management files, and links cannot be deleted with the delete_$ptr entry 
point The directory_sw, link_sw, and chase_sw switches are not examined by this 
entry point, but must be present 

USAGE 

declare delete_$ptr entry (ptr, bit (6), char (*) , fixed bin (35)). 
call delete_$ptr (seg_ptr, switches, caller, code); 
ARGUMENTS 
seg_ptr 

is a pointer to the segment to be deleted. (Input) 

switches 

are switches that specify the actions to be taken. (Input) (See the delete_$path 
entry point). 

caller 

is the name of the calling procedure, to be used when questions are asked. 
(Input) 

code 

is a storage system status code. (Output) 



Name: dial manager 

The dial_manager_ subroutine is the user interface to the answering service dial 
facility. The dial facility allows a process to communicate with multiple terminals at 
the same time. This subroutine uses a structure, dial_manager_arg, to receive arguments 
from its caller. This structure is described below, under "Notes". For more 
information, see the description of the dial command in the the Commands manual. 

The dial_manager_ subroutine uses an event channel to communicate with the 
answering service. This event channel is specified by dial_manager_arg.dial_channel. 
The channel must be created by the caller. The answering service sends notices of dial 
connections and hangups over this channel. The dial_manager_ subroutine goes blocked 
on the event-wait channel awaiting a response to the request from the answering 
service. When the user program receives wakeups over this channel, it should call the 
convert_diai_message_ subroutine to decode the event message. 
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The dial_manager_$allow_dials and dia!_manager_$registered_server entry points establish 
a dial line. The dial_id specified in dial_manager_arg.dial_qualifier is used as the first 
argument to the dial command when connecting a terminal to a process. The dial_id 
may be an alphanumeric string from 1 to 12 characters long. The dial_id "system" 
and "s" are reserved for the Initializer process. A process can have only one dial line 
active at a time. 



Entry: dial__manager__$allow_dials 

This entry point requests that the answering service establish a dial line to allow 
terminals to dial to the calling process. The caller must set dial_manager_arg.dial_qualifier 
to the dial_id for the dial line. The caller must also set dial_manager_arg.dial_channel 
to an event-wait channel in the caller's process. After the dial_manager_$allow_dials 
entry point has been called, the event channel may be changed to an event-call 
channel. To connect a terminal to the process, the User_id of the process must be 
specified as the second argument of the dial command. If the process has already 
established another dial line, the request is rejected and code is set to 
error_table_$dial_active. 

USAGE 

declare di a1_manager_$al low_di als entry (ptr, fixed bin (35) ) ; 
call dial jnanager_$al low_dials (request_ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 
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Entry: dial manager__$dial out 

This entry point is used to request that an auto call channel be dialed to a given 
destination and, if the channel is successfully dialed, that the channel be assigned to 
the requesting process. The caller must set dial_manager_arg.dial_out_destination to the 
telephone number to be dialed. The caller must also set dial_manager_arg.dial_channel 
to an event-wait channel in his process. The answering service sends notice of dial 
completions and hangups over this channel. After the dial_manager_$dial_out entry 
point has been called the event channel may be changed to an event-call channel. The 
user programs receiving the wakeup should call the convert_dial_message_ subroutine to 
decode the event message. The caller may set dial_manager_arg.channel_name to the 
name of a specific channel to be used. It is also possible to set 
dial_manager_arg.channel_name to a starname, in which case the answering service 
chooses a channel that has a matching name and has all the attributes specified in 
dial_manager_arg.reservation_string. The name of the chosen channel is not returned 
by dial_manager_; it must be obtained via a call to convert_dial_message_. 

USAGE 

declare d i a l_manager_$d i a l_out entry (ptr. fixed bin (35)) J 
call dial_manager_$di al_out (request_ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 

code 

is an error status indicator. (Output) It can assume any value documented in the 
convert_dial_message_ description (earlier in this manual), or one of the following: 
error_table_$bad_conversion 

a reservation_string value (BAUD_RATE) was not a proper decimal value. 
error_table_$invalid_line_type 

the value of LINE_TYPE is not acceptable. 
error_table_$bad_arg 

reservation_string contains an unrecognized attribute. 
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Entry: dial manager Sprivileged attach 

This entry point allows a privileged process to attach a "slave" channel. The effect is 
as if that terminal had dialed to the requesting process. The caller must set all 
variables required by the dial_manager_$allow_dials entry point and then must set 
dial_manager_arg.channel_name to the name of the channel that is to be attached; 
dial_manager_arg.dial_qualifier is not used and should be set to the null string. This 
must be the same name as specified by the channel master file. The slave service type 
must be specified for this channel in the channel master file. The calling process must 
have rw access to the access control segment <channel_name>.acs in >scl>rcp if 
this request is to be honored. 

USAGE 

declare di al_manager_$pr ivi leged_attach entry (ptr, fixed bin (35)); 
call di al_manager_$pr i vi leged_attach (request_ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 



Entry: dial manager Sregistered server 

This entry point is used to request that the answering service establish a dial line to 
allow terminals to dial to the calling process using only the dial qualifier. The calling 
process must have rw access to the access control segment dial. <d i a 1 qualifier>.acs 
in >scl>rcp if this request is to be honored. If the process has already established a 
dial line, the request is rejected and code is set to error_table_$dial_active. 

USAGE 

declare d i al_manager_$reg i stered_server entry (ptr, fixed bin(35))» 
call dial_manager_$regi stered_server (request_ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 
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Entry: dial_manager $release_ .channel 

This entry point is used to request the answering service to release the channel 
specified in channel_name. This channel must be dialed to the caller at the time of 
this request The caller must set dial_manager_arg.dial_channel to an event wait 
channel in the caller's process. The caller also must set diaLmanager_arg.channel_name 
to the name of the channel to be released. The user must make 
dial_manager_arg.diaLchannel an event-wait channel before using this call. If the 
channel was dialed, the channel is returned to the answering service and another access 
request may be issued. If the channel is a slave channel, the channel is hung up. 

USAGE 

declare dial_manager_$release_channel entry (ptr, fixed bin (35)); 
call di al_manager_$rel ease_channel (request_ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 



Entry, dial manager $release_channel no hangup 

This entry point performs the same function as the dial_manager_$release_channel 
entry point except that slave channels are not hung up. 



Entry: dial manager $release_dial id 

This entry point functions as does dial_manager_$shutoff_dials, except that dialed 
terminals are not hung up. The user can later release dialed terminals by a call to 
dial_manager_$shutoff_dials or by calls to dial_manager_$release_channel. 

USAGE 

declare dia1_manager_$release_dial__id (ptr, fixed bin (35) ) » 
call dial_manager_$re1ease_dial_id (request_ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 
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code 

is a standard status code, (Output) 



Entry: dial_manager_$release_no_listen 

This entry point requests the answering service to release the channel specified in 
channel_name, which must have been attached by means of the dial_manager_$tandd_attach 
entry point The channel is left in a hung-up state and is not available for use until 
an explicit "attach" operator command is issued for the channel. This entry point has 
the same requirements as the diaLmanager_$release_channel entry point 

USAGE 

declare di al_manager_$release_no_l isten entry (ptr, fixed bin (35) ) » 
call dial jnanager_$release_no_l i sten (request_ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 



Entry: dial manager_Sshutoff__diaIs 

This entry point informs the answering service that the user process wishes to prevent 
further dial connections, and that existing connections should be terminated. The same 
information should be passed to this entry point as was passed to the 
dial_manager_$allow_dials or dial_manager_$registered_server entry point The dial__channel 
must be an event-wait channel. 

USAGE 

declare di al jnanager^Sshutof f_di al s (ptr, fixed b i n (35) ) S 
call dial_manager_$shutof f_dia1 s (request _ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 



2-225 



AG93-05 



dial_manager_ 



dial_manager_ 



| Entry: dial_manager_$tandd attach 

This entry point allows a process with appropriate access to attach any communications 
channel that is in the channel master file and not already in use, for the purpose of 
performing online testing of the channel. The requesting process acquires the channel 
in a hung-up, nonlistening state. The channel can be released using either the 
dial_manager_$release_channel or the dial_manager_$release_no_listen entry point In 
the latter case, the channel will be unavailable to users until the operator enters an 
attach command for the channel. The caller must set all the variables required by the 
dial_manager_$privileged_attach entry point; dial_manager_arg.dial_qualifier is not used 
and should be set to the null string. 

USAGE 

declare d i al_manager_$ tandd_attach entry (ptr, fixed bin (35)); 
call d i al_manager_$tandd_attach (request_ptr , code); 
ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 
ACCESS REQUIRED 

The caller must have at least rw access to both >sc l>rcp>tandd .acs and 
>scl>rcp>CHANJJANE.acs, where CHAN_NAME is the name of the channel to be 
attached. 



Entry: dial manager Sterminate dial out 

This entry point is used to request that the answering service hang up an auto call 
line and unassign it from the requesting process. The caller must set 
dial_manager_arg.channel_name to the name of the channel being used; channel_name 
cannot be null. The caller also must set diai_manager_arg.dial_channei to an 
event-wait channel. 

USAGE 

declare dial_manager_$terminate_dial_out entry (ptr, fixed bin (35)) 5 
call d i al_manager_$termi nate_d i al_out (request_ptr , code); 
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ARGUMENTS 
request_ptr 

is a pointer to the dial_manager_arg structure. (Input) See "Notes" below. 

code 

is a standard status code. (Output) 



This structure is used to pass a variety of information to the dial_manager_ 
subroutine. It is declared in dial_manager_arg.incl.pll. It has the following declaration: 



STRUCTURE ELEMENTS 
version 

indicates the version of the structure that is being used. This is set by the caller 
and must be dial_manager_arg_version_4. 

dial_qualifier 

is the dial qualifier for calls to the dial_manager_$allow_dials, 

dial_manager__$registered_server, dial_manager„$shutoff_dials, and 

dial_manager_$release_dial_id entry points. This field should be set to blanks if it 
is not used. 

dial_channel 

is an interprocess communication channel used to receive messages from the 
answering service. The channel must always be an event-wait channel at the time 
a call to any dial_manager_ entry is made. v If the value of dial_channel is 0, 
then the answering service will not send any status messages to the requesting 
process. 



NOTES 



del 1 dial_manager_arg 



2 version 

2 dial__qual i f i er 

2 dial__channel 

2 channel _name 

2 dial_out_dest i nation 

2 reservat ion_str ing 

2 dialjnessage 

2 access_class 

2 flags 



3 accessed ass__requi red 
3 pr ivi leged_operation 
3 mbz 



based al i gned, 
fixed bin, 
char (22) , 
fixed bin (71) * 
char (32), 
char (32), 
char (256) , 
f ixed bin (71) ; 
bit (72), 
al i gned, 

bit (1) unal igned, 
bit (1) unal i gned, 
bi t (3*0 unal i gned; 
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channel_name 

In calls to the dial_manager_$privileged_attach entry point it indicates which slave 
channel to attach. In calls to the dial_manager_$dial_out entry point, it indicates 
which autocall channel should be used for a dial_out attempt. For these two 
entries, the following convention is observed: the caller can fully specify a 
channel name or can use the star convention to specify a group of channels from 
which the answering service is to pick one. This name is matched against both 
the channel name in the cdt and the generic_destination field for the channel, if 
one exists. 

dial_out_destination 

is used for calls to the dial_manager_$dial_out entry point. Interpretation of this 
value is determined by the multiplexer that controls the channel being dialed out 
The standard FNP multiplexer interprets this value as a telephone number and 
ignores all characters except decimal digits and the exclamation point (!). It 
recognizes "!" as a dial-tone-wait character and will suspend dialing until the 
autocall unit receives a dial tone. Any number of "!" characters can exist in a 
dial_out_destination, and the standard FNP multiplexer will pause at each. This 
field should be set to blanks if it is not used. 

When the destination specifies an X.25 address it may optionally be preceded by 
"*" or "x29," to indicate that an X.29 (PAD) call should be made. For example, 
a destination of 

x.29,3106:mitmul or 
*3106:mitmul 

specifies an X.29-type call on TYMNET. 

reservation_string 

is used to specify the desired characteristics of a channel in calls to the 
diai_manager_$diaI_out entry. The reservation string (which can be null), consists 
of reservation attributes separated by commas. The channel used by a dial-out 
operation must have the characteristics specified in the reservation string. 
Reservation attributes consist of a keyword and optional argument. Attributes 
allowed are: 

baud_rate=BAUD_RATE 
1 ine_type=LINE_TYPE 

The attribute name, such as "baud_rate", must appear literally in the string. 
BAUD_RATE is a decimal representation of the desired channel line speed and 
must appear in a baud_rate attribute. LINEJTYPE is a valid line type, chosen 
from line_types.incl.pll and must appear in a line_type attribute. Examples: 
"baud_rate=300, line_type=ASCII", "line_type=BSC". This field should be set to 
blanks if it is not used or no particular channel attributes are required. 
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dial_message 

is a copy of the dial_message received from the answering service. The 
dial_manager_ subroutine makes an answering service request based upon the 
arguments supplied by its caller; it then waits for a reply from the answering 
service. This reply is converted using convert_diaLmessage_, and some of the 
results of the conversion are immediately available to dial_managerj callers as 
output arguments. To obtain other portions of the diaLmessage absorbed by 
diaLmanager_, the user must call convert_dial_message_ specifying the value of 
this field. This field is set to -1 if an error occurs in the dial_manager_ or 
answering service request; convert_dial_message_ rejects attempts to convert such a 
message with the return code error_table$badcall. (Output) 

access.class 

is the access class to be associated with the channel to be attached by the 
dial_manager_$dial_out or dial_manager_$privileged_attach entry. It is only used if 
access_class_required (below) is "l"b. It must be the same as the requesting 
process's max authorization, unless the process has the "comm" privilege set, in 
which case access_class must be equal to or lower than the requesting process's 
authorization. (Input) 

access_class_required 

if "l"b, indicates that the channel to be attached by the dial_manager_$dial_out 
or dial_manager_$privileged_attach entry must have the access class specified by 
access_class (above) or must be a mult-class channel whose access class can be set 
to access_class. 

privileged_operation 

If 'T'b, indicates that a call to dial_manager_$accept_dials or 
dial_manager_$registered_server should establish a privileged dial server. For 
example, one which accepts channels whose access class is in the range 
system_low:access_class. 

mbz 

must be "0"b. 



Name: display access class 

The display_access_class_ function converts a bit(72) aligned representation of an access | 
authorization or access class into a character string of the form: 

L L • • • L * C C • • • C 

where LL...L is an octal sensitivity level number, and CC...C is an octal string 
representing the access category set. 
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USAGE 

declare display_access_class_ entry (bit(72) aligned) 
returns (char (32) aligned); 

aim_chars - display_access_class_ (aim_bits); 

ARGUMENTS 

aim_bits 

is the binary representation to be converted. (Input) 
aim_chars 

is the character string representation. (Output) 
NOTES 

Only significant digits of the level number (usually a single digit from 0 to 7) are 
printed. 

Currently, only 18 access category bits are used, so that only six octal digits are 
required to represent access categories. Therefore, aim_chars is padded on the right 
with blanks, which may be used at a later time for additional access information. 
Trailing zeros are NOT stripped. 

If either the level or category field of aim_bits is invalid, the erroneous field is 
returned as full octal (6 digits for level, 12 digits for category), followed by the string 
"(undefined)". 



Entry: display access class Srange 

The display_access_class_$range function converts an AIM access class range to a 
character string when the names of levels and categories are not available. 

USAGE 

declare d i spl ay_access_c 1 ass_$range entry ((2) bit (72) aligned) 
returns (char (32) aligned); 

string_range = d i spl ay_access_c 1 ass_ (AIM_range) ; 

ARGUMENTS 

AIM_range 

is a standard access class range. (Input) 
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string_range 

is a string of the form: 

1 :cccccc-L:CCCCCC 

where 1 is the level, from 0 to 7, of the bottom of the range. (Output) 
cccccc are .the categories of the bottom of the range. 

The categories are a bit string (one bit per category) represented in octal. 

L is the level, from 0 to 7, of the top of the range. 
CCCCCC are categories of the top of the range. 

The categories are a bit string (one bit per category) represented in octal. 
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Name: display_file value 

The display _file_value_ subroutine outputs information about a file on a user-supplied 
switch. 

USAGE 

del di splay_f i le_value_ entry (ptr, file, fixed bin (35)); 
call d i spl ay_f i 1 e_val ue_ (switch, a_file, code); 
ARGUMENTS 
switch 

is a pointer to the iocb of the switch on which output is to be written. If it is 
null, then iox_$user_output is used. (Input) 

a_file 

is the file, variable, or constant whose value is to be displayed. (Input) 

code 

is a standard status code. (Output) 
NOTES 

The output produced is, first, the values of the two pointers that comprise a file. If 
the file is closed, then a note to that effect is produced, and the values of the file 
attribute block are given, and that is all. 

For all open files, the file name, address of its iocb, and pathname are given. If the 
file is neither stream nor record type, or if it is both, then a note to the effect that 
the fsb is inconsistent is given. Attributes relevant to the type of file (stream or 
record) are given. For stream input files, the current input buffer is printed, with a 
circumflex above the next character that is to be parsed. 



Name: dl handler 

This subroutine has three entry points that issue queries for each of three situations 
involving deletion. These situations are: 

Deletion of an entry whose safety switch or copy switch is on. 
Deletion via a starname that matches all entries, e.g. "**". 
Deletion of a directory (delete_dir always queries). 

This subroutine returns a status code depending on the user's answer. If the user 
answers "yes", all three entry points turn off the safety and copy switches, and in the 
case of a directory, set sma to the user before returning. 
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The dl_handler_ entry point, called when an entry has its safety switch or copy switch 
on, issues a query of the form: 

<caller>: <path> is protected. Do you want to delete it? 

If the user answers yes, dl_handler_ turns off both switches and returns a zero status 
code. 

USAGE 

del dl_handler_ entry (char (*) , char (*) , char (*) , fixed bin (35)); 

call dl_handler_ (caller, dn, en, code); 

ARGUMENTS 

caller 

is the name of the calling program, used to print the query. (Input) 



is the directory name. (Input) 

en 

is the entry name. (Input) 

code 

is a standard status code. (Output) It can be: 

0 the user answered yes, switches have been turned off, and the entry can now 

be deleted. 
error_table_$action_not_perf ormed 

the user answered no. 
other codes 

the switches could not be turned off. 

The two other entry points have the same calling sequence as dl_handler_. 



Entry: dl handler Sdblstar 

This entry point issues the query: 

Do you want to '<caller> <en>' in <dn>? 

where caller, the name of the calling program, is assumed to be a suitable verb. This 
entry point is called, for example, by the delete and unlink commands, which also 
pass a double stamame as the value of en: 

Do you want to 'delete **' in <dir_path>? 
Do you want to 'unlink **' in <dir_path>? 
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Entry: dl_handler Sdirdelete 

This entry point assumes it is given a directory pathname, and issues the query: 

<cal1er>: Do you want to delete the directory dn>en? 
This entry point is called, for example, by the delete_dir command. 



Name: dprint 

This subroutine contains several entry points used to submit requests to the I/O 
daemon for printing or punching of segments and multisegment files. 

Entry: dprint 

The dprint_ entry point adds a request to print, punch, or plot a segment or 
multisegment file to the specified queue. 

USAGE 

declare dprint_ entry (char (*) , char (*) , ptr, fixed bin (35)); 
call dprint_ (dir_name, entryname, dpr i nt_arg_ptr , code); 
ARGUMENTS 
dir_name 

is the absolute pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment, multisegment file, or link to the segment or 
multisegment file to be printed, punched, or plotted. (Input) 

dprint_arg_ptr 

is a pointer to the dprint_arg structure (described in "Notes" below) that defines 
the options for this request If this pointer is null, the default settings are used 
for all options. (Input) 

code 

is a standard status code. (Output) 
NOTES 

The dprint_ subroutine uses the following structure, defined in the system include file 
dprint_arg.incl.pll, to determine the details of the request If no structure is supplied, 
default values are used. 
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dpr i nt_arg 


based al i gned, 


2 


vers i on 


fixed bin, 


2 


copi es 


fixed bin, 


2 


delete 


f i xed bin, 


2 


queue 


fixed bin, 


2 


pt_pch 


fixed bin, 


2 


not i f y 


fixed bin, 


2 


headi ng 


char (64) , 


2 


outputjnodule 


fixed bin, 


2 


dest 


char (12) , 


2 


carr i age_control , 






3 nep 


bi t (1) unal igned, 




3 single 


b i t (1) unal i gned , 




3 non_ed i ted 


bi t (1) unal i gned, 




3 truncate 


bi t (1) unal i gned, 




3 center_top_l abel 


bi t (1) unal i gned, 




3 center_bottom_l abel bit(l) unaligned, 




3 esc 


bi t (1) unal i gned, 




3 no_separator 


bi t (1) unal igned, 




3 padding 


bi t (28) unal igned, 


2 


pad (30) 


f F xed bin (35) » 


2 


forms 


char (8) , 


2 


lmarg i n 


fixed bin, 


2 


1 i ne_l th 


fixed bin, 


2 


cl ass 


char (8) , 


2 


page_l th 


fixed bin, 


2 


top_l abel 


char (136) , 


2 


bottom_l abel 


char (136) , 


2 


bi t_count 


f i xed bi n (35) » 


2 


for ni_narne 




2 


dest i nat i on 


char (24) , 


2 


chan_stop_path 


char (168) , 


2 


request_type 


char (24) unal i gned , 


2 


defer_unti l_process 


_termi nat ion fixed bin; 
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STRUCTURE ELEMENTS 
version 

is the version number of the structure. This is set by the caller and must be the 
value of the named constant dprint_arg_version_8 also defined in the include file. | 

copies 

is the number of copies requested. * 
delete 

indicates whether the file is to be deleted after printing, punching, or plotting. 
1 deletes the file. 

0 does not delete the file. * 
queue 

is the priority queue in which the request is placed. If zero is supplied, the 
default queue of the specified type request will be used. 

pt_pch 

indicates whether the request is for printing, punching, or plotting. 

1 print request * 

2 punch request 

3 plot request 

notify 

indicates whether the requestor is to be notified when the request is completed. 
1 notifies the requestor 

0 does not notify the requestor * 
heading 

is the string to be used as a heading on the front page of the output If it is a 
null string, the requestor's Person_id is used. * 

output_module 

indicates the I/O module to be used in executing the request. 

1 indicates printing * 

2 indicates 7-punching 

3 indicates Multics card code (mcc) punching 

4 indicates "raw" punching 

5 indicates plotting 

dest 

is not used. See destination below. 

nep 

indicates whether no-endpage mode is used. 
"l"b yes 

"0"b no * 
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single 

indicates whether single mode, which causes all vertical tabs and new pages to be 
converted to new lines, is used. 
'T'b yes 
"0"b no 

non_edited 

indicates whether nonedited mode, which causes all nonprinting control characters 
and non-ASCII characters to be printed as octal escape sequences, is used. 
'T'b yes 
"0"b no 

truncate 

indicates whether truncate mode is used. 
T'b yes 
"0"b no 

center_top_label 

indicates whether the top label should be centered. 
T'b yes 
"6"b no 

center_bottom_label 

indicates whether the bottom label should be centered. 
'T'b yes 
"(Tb no 

esc 

indicates whether escape sequences in the print file should be recognized. 
'T'b yes 
"0"b no 

no_separator 

indicates when multiple copies of a request are processed, whether the inner head 
and tail sheets should be printed. 
'T'b no 
"0"b yes 

padding 

is not used. 

pad 

is not used, 
forms 

is not used. See form_name below, 
imargin 

indicates the left margin position. 
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line_lth j 
indicates the line length. If supplied as -1, the maximum line length for the j 
specified request type will be used. | 

class 

is not used. See request_type below. 
page_lth 

indicates the page length, i.e., the number of lines per logical page. If supplied 
as -1, the physical page length will be used. 

top_label 

is a label to be placed at the top of every page. * 
bottom_label 

is a label to be placed at the bottom of every page. * 

bit_count 

is the file's bit count. 

form_name 

is the name of special forms needed. 

destination 

is the string to be used to indicate where the output should be delivered. If it is 
null, the requestor's Project_id is used. * 

chan_stop_path 

is the path of user channel stops. 

request_type 

is the request type name to be used to queue the request. If printing is 
requested, the request type must be of the generic type "printer"; if punching is 
requested, the request type must be of generic type "punch."; if plotting is 
requested, the request type must be of generic type "plotter". * 

def er_until_process_termination 

indicates whether the request should be deferred until the requesting process 
terminates. 

1 defers the request. 

0 does not defer the request. * 
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Entry: dprint Scheck daemon__access 

This entry point checks the I/O daemon's access to a given segment or multisegment 
file. It returns whether the daemon responsible for a given request type has "r" access 
to the file and "s" access to the containing directory and whether the I/O daemon 
coordinator can delete the file if requested. 

USAGE 

declare dpr i nt_$check_daemon_access entry (char (*) , char (*) , char (*) , 
bit(l) aligned, bit(l) aligned, bit(l) aligned, char (*) , 
fixed bin (35)) 5 

call dpr i nt_$check_daemon_access (dirname, entryname, request_type, 
del ete_permi ssion, read_permi ssion, status_permi ss ion, 
dr i ver_user id, code); 

ARGUMENTS 

~ 

is the absolute pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment, or multisegment file, or a link to the segment 
or multisegment file for which the daemon's access is to be checked. (Input) 

request_type 

is the name of the request type in which a request to print, punch or plot the 
file will be placed. The access of the driver process for this request type will be 
returned. (Input) 

delete_permission 

indicates whether the I/O coordinator has sufficient access to delete the file if 
requested. The coordinator requires "m" access to the containing directory to 
delete the file. (Output) 

read_permission 

indicates whether the driver process of the given request type has "r" access to 
the given segment or multisegment file. (Output) 

status_permission 

indicates whether the driver process of the given request type has "s" access to 
the directory containing the segment or multisegment file. (Output) 

driver_userid 

is the name of the process that processes requests for the specified type. This 
value is in the form "Person_id.?roject_id.*". (Output) 

code 

is a standard system status code. (Output) 
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NOTES 

The user must have "s" access to the directory containing the segment or multisegment 
file to determine whether the driver has read access to the file. 

The user must have "s" access to the directory containing the directory containing the 
segment or multisegment file in order to determine whether the I/O coordinator can 
delete the file and whether the driver process has "s" access to the containing 
directory. 



Entry: dprint_$request_id 

This entry point adds a request to print, punch, or plot a segment or multisegment 
file to the specified queue, and returns the message identifier of the queue entry 
being made. 

USAGE 

declare dpr i nt_$request id entry (char (*) , char (>*0 , ptr, fixed bin (71). 
fixed bin(35)) ; 

call dpr int_$request_id (dir_name, entryname, arg_ptr, requested, 
code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment, multisegment file, or link to the segment or 
multisegment file to be printed, punched, or plotted. (Input) 

dprint_arg_ptr 

is a pointer to the dprint_arg structure (described in system include file 
dprint_arg.incl.pll) that defines the options for this request If this pointer is 
null, the default settings are used for all options. 

requested 

is the message identifier of the request being enqueued. (Output) 

code 

is a standard status code. (Output) 
NOTES 

The dprint_$request_id entry uses the structure defined in the system include file 
dprint_arg.incl.pll to determine the details fo the request If no structure is supplied, 
default values are used. 
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Entry: dprint_$queue_contents 

This entry point returns the number of requests in a specific I/O daemon queue. 
USAGE 

declare dpr i nt_$queue contents entry (char (*) , fixed bin, fixed bin, 
fixed bin (35)) 

call dpr i nt_$queue_contents (request_type, queue, n_requests, code); 

ARGUMENTS 

request_type 

is the name of the request type whose queue is to be checked. (Input) 
queue 

is the number of the queue to be examined. If -1 is specified, the default queue 
of the given request type is checked and the number of the default queue is 
returned in this parameter. (Input/Output) 

n_requests 

is the number of requests in the specified queue. (Output) 

code 

is a standard system status code. (Output) 



Name: dump segment 

This subroutine prints the dump of a segment formatted in the same way as the 
dump_segment command would print it The output format is controlled by a bit 

string that allows most of the formatting control arguments available to dump_segmenL 

USAGE 

declare dump_segment entry (ptr, ptr, fixed bin, fixed bin(l8), 
fixed bin (18) ,"bit (*)) ; 

call dump_segment_ (iocb_ptr, first, block_size, offset, count, format); 

ARGUMENTS 

iocb_ptr 

is a pointer to the I/O control block that specifies where the dump is to be 
written. (Input) 
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first 

is a pointer to the first word of the data to be dumped. (Input) 
biock_size 

is the number of words in the block if blocked output is desired. If unblocked 
output is desired, this is zero. (Input) 

offset 

is an arbitrary offset to be printed in addition to the address of the first word 
of data to be dumped if the offset option in the format string is specified. (It is 
reset to this initial value at the start of each block.) (Input) 

count 

is the number of words to dump, starting with the word pointed to by first 
(Input) 

format 

is a format control bit string with the following definition: (See the dump_segment 
command in the Muitics Commands and Active Functions Manual, Order No. 
AG92, for a full discussion of these arguments.) (Input) 
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Entry: dump segment__$string 

This entry point returns the formatted dump of a segment. The ouput format is 
controlled by a bit string that allows most of the formatting control arguments 
available to the dump_segment command. 

USAGE 

del dump_segment_$str i ng entry (ptr, fixed bin (21), ptr, fixed bin, 
fixed bin (18) , fixed bin (18) , bit (*) ) ; 

call dump_segment_$str i ng (string_ptr, str i ng_l ength, first, block_size, 
offset, count, format) 

ARGUMENTS 

string_ptr 

is the pointer to the varying character string to place the output in. (Input) 
string_length 

is the maximum length of the varying character string. (Input) 

first 

is the pointer to the first word of data to be dump. (Input) 
block_size 

is the output dump in blocks of this number of words. (Input) 
offset 

is an arbitrary offset to be printed in addition to the address of the first word 
of data to be dumped if the offset option in the format string is specified. (It is 
reset to this initial value at the start of each block.) (Input) 

count 

is the number of words to be dump. (Input) 
format 

is the bit string controlling the output modes. (Input) Described in 
dump_segment_format.incl.pll. 
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NOTES 

The following structure is declared in dump_segment_format.incl.pll. 
del 1 dump_segment_f ormat_structure based aligned, 
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STRUCTURE ELEMENTS 
address 

prints the address (relative to the base of the segment) with the data, 
offset 

displays the offset of the first word to be dumped, 
short 

compacts a line to have four words per line. 

bed 

interprets data as BCD. 

ascii 

interprets data as ASCII. 

long 

formats a display line to have 8 words per line. 
ebcdic9 

interprets data to be EBCDIC (9-bits). 
ebcdic8 

interprets data to be EBCDIC (8-bits). 
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bit4 

translates data to be 4-bit data. 

hex8 

translates data to be with 8 hexadecimal digits per word. 

hex9 

translates data to be with 9 hexadecimal digits per word. 

octal 

raw data is octal, 
header 

displays a header line containing the pathname of the segment being dumped. 

raw_data 

displays the raw data. 

interpreted_data 

displays the interpreted data. 

suppress_duplicates 

replaces multiple duplicate lines with a single line of equal signs. 

command_output 

if on, the format of the data returned is identical to the format of the 
dump_segment command. If off, the format of the data returned is in word 
format (i.e., if the raw data is being returned, the data is returned in the format 
of words, with each word separated by a blank; if the interpreted data is being 
returned, the data is returned in the format of a single string, requoted if 
necessary). 

mbz 

must be zero. 



Name: ebcdic_to_ascii 

The ebcdic_to_ascii_ subroutine performs isomorphic (one-to-one reversible) conversion 
from EBCDIC to ASCII. The input data is a string of valid EBCDIC characters. A 
valid EBCDIC character is defined as a 9-bit byte with a hexadecimal value in the 
range 00 <= hex_value <= FF (octal value in the range 000 <= oct_value <= 377). 

This entry point accepts an EBCDIC character string and generates an ASCII character 
string of equal length. 
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USAGE 

declare ebcd i c_to_asc i i_ entry (char (*) , char (*) ) ; 
call ebcdic_to_asci i_ (ebcdic__in, ascii_out); 
ARGUMENTS 
ebcdic_in 

is the string of EBCDIC characters to be converted. (Input) 
ascii_out 

is the ASCII equivalent of the input string. (Output) 



Entry: ebcdic to ascii $ea__table 

This entry point defines the 256-character translation table used to perform conversion 
from EBCDIC to ASCII. Of the 256 valid EBCDIC characters, only 128 have ASCII 
equivalents. These latter 128 characters are defined in the Isomorphic ASCII/EBCDIC 
Conversion Table (in tlic ascii_to_cbcdic_ subroutine description.) For defined 
characters, the mappings implemented by the ebcdic_to_ascii_ and ascii_to_ebcdic_ 
subroutines are isomorphic; i.e., each character has a unique mapping, and mappings 
are reversible. An undefined (but valid) EBCDIC character is mapped into the ASCII 
SUB (substitute) character, octal 032; the mapping of such a character is anisomorphic. 
The result of converting an invalid character is undefined. 

USAGE 

declare ebed i c_to_asc i i_$ea_tabl e char (256) external static; 
NOTES 

Calling the ebcdic_to_ascii_ subroutine is extremely efficient, since conversion is 
performed by a single MVT instruction and the procedure runs in the stack frame of 
its caller. 
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Name: enter - _abs_request 

This subroutine is used to request the creation of an absentee process. 

Entry: enter__abs__request_. Senter abs request 

This entry point adds a. request to create an absentee process. 
USAGE 

del enter_abs_request_ entry (ptr, ptr, fixed bin (35) ) » 

call enter_abs_request_ (abs_request_i nf o_ptr , abs_return_i nf o_ptr , 
code) ; 

ARGUMENTS 

enter_abs_request_inf o_ptr 



r_aDs_request_int o_ptr 

is a pointer to the abs_request_info structure (described in system include file 
abs_request_dcls.incl.pll) that defines the options for this request (Input) 

abs_return_inf o_ptr 

is a pointer to the abs_return_info structure (described in system include file) that 
gives information pertaining to the request's status in the queue. 

code 

is a standard status code, (Output) 
NOTES 

The enter_abs_request_subroutine uses the structure defined in abs_request_dcls.incl.pll. 



del 1 abs_request_i nf o 

2 version 

2 resource_length 

2 comment_length 

2 max_arg_length 

2 arg_count 

2 proxy__personid 

2 proxy_projectid 

2 queue 

2 def erred_t ime 

2 max_cpu_t ime 

2 requested_author ization 

2 i nput_segment_d i rname 

2 i nput_segment_entryname 

2 output_segment_di rname 

2 output_segment_entryname 



structure aligned based 

(abs_request_i nf o_ptr) , 
char (8) aligned* 
fixed bin, 
fixed bin, 
fixed bin, 
fixed bin, 
char (22) aligned, 
char (9) al igned, 
char (**) aligned, 
f i xed bin (71) , 
f ixed bin (35) » 
bit (72), 

char (168) unaligned, 
char (32) unaligned, 
char (168) unaligned, 
char (32) unaligned, 
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2 attributes 
3 restartable 

3 user_def erred_i ndef i ni tely 
3 secondary__ok 
3 truncate_absout 
3 notify 

3 attr ibutesjnbz 
2 resource 

2 sender 
2 comment 

2 arguments 



del 1 abs_return_i nf o 

2 version 
2 requested 
2 queue 

2 queue_requests__count 
del (abs_request_i nf o_ptr , abs_return 



del ( 

ABSENTEE_REQUEST_I NF0_VERS 1 0N_2 

ABSENTEE RETURN INFO VERS ! 0 W 2 



/**** The following fields should be 

al located */ 
del arqi_resource_length 
del arqi_comment_length 
del arq i_max_arg_l ength 
del arq i_arg_count 

del ( 

BACKGROUND_QUEUE 

FOREGROUND_QUEUE 
DEFAULT_QUEUE 

) 



al i gned, 

bit (1) unaligned, 

bit (1) unaligned, 

bit (1) unal i gned, 

bit (1) unaligned, 

bit (1) unaligned, 

bit (3D unaligned, 

char (arq i__resource_l ength refer 

(abs request i nfo. resource length)), 
char (32) , 

char (arq i_comment__l ength refer 

(abs_request_i nf o.comment_l ength) ) , 

dimension (arqi_arg_count refer 
(abs_request_i nf o.arg_count) ) 

char (arq i_max_arg_l ength refer 
(abs_request__i nf o.max_arg_l ength) ) 
vary i ng; 

structure aligned based 
(abs__return_i nf o_ptr) , 
char (8) ai i gned, 
f i xed bin (71), 
char (it) al i gned, 
fixed bin (17) ♦ 

_i nfo_ptr) 
ptr automatic; 

initial ("arqi 002") , 
initial ("art i~002") 
char (8) internal static options 
(constant) ; 

set before abs_request__i nf o is 

fixed bin; 
fixed bin; 
fixed bin; 
fixed bin; 



dimension (0:**) init ("0", "1", 

"2", "3", "V) , 
init ("fg"), 
init ("dft") 
char (4) al i gned 

internal static options (constant); 
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ARGUMENTS 
version 

should be set to the constant ABSENTEE_REQUEST_DCLS_VERSION_2. 

resource_length 

is the length of the resource field. 

comment_length 

is the length of the comment field. 

max_arg_length 

is the maximum length of any element in the arguments array. 
arg_count 

is the number of arguments in the arguments array. 
proxy_personid 

enters the request on behalf of the specified user. An absentee process of that 
User_id is logged in to run the job. The system administrator controls the use of 
-proxy by an access control segment. 

queue 

specifies which absentee queue the request should be placed in. It can be the 
number of the queue, "0", "1", "2", "3 H , or "4", or "fg" to specify the foreground 
queue, or "dft" to specify the default queue. 

deferred_time 

delays the creation of the absentee process until the specified time. 
max_cpu_time 

is the limit on the CPU time used by the absentee process. The parameter N 
must be a positive decimal integer specifying the limit in seconds. If N equals 0, 
the default limit, which is defined by the site for each queue, is used. 

requested_authorization 

The authorization that the absentee job is requested to be run. 

input_segment_dirname 

is the directory containing the absentee control segment. 

input_segment_entryname 

is the absentee control segment name. 

output_segment_dirname 

is the directory to contain the output segment. If this argument is a null string, 
then the output of the absentee process is put in the directory containing the 
absentee control segment, input_segment_dirname. 
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output_segment_entryname 

is the name of the output segment If output_segment_entryname is a null string, 
the output of the absentee process is directed to a segment whose entryname is 
the same as the input_segment_entryname, except having the suffix absout instead 
of absin. 

restartable 

indicates that the absentee computation should be started over from the beginning 
if interrupted. 

user_def erred_indef initely 

indicates that the job is deferred until the operator takes action to run it. 

secondary_ok 

indicates that a foreground job can be logged in as a secondary user. 
truncate_absout 

indicates that the output_segment should be truncated before the absentee job is 
run. 

resource 

is a resource, such as a tape drive, needed by the job. The resource is reserved 
for the absentee job before it is logged in. If resource is set to the string no 
resource will be reserved. 

sender 

is used by the RJE facility to give the name of the RJE station that is requesting 
the absentee process to be created. If the absentee process is to be that of the 
user, sender should be set to the string ,m . 

comment 

is a comment which will be associated with the request The comment is printed 
whenever the absentee request is listed. 

arguments 

is a sequence of arguments to the absentee control segment 
ari_resource_length 

is the maximum length of abs_request_info.resource. This value should be set 
before allocating the structure. 

ari_comment_length 

is the maximum length of abs_request_info. comment This value should be set 
before allocating the structure. 
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ari_arguments_length 

is the maximum length argument in the arguments array. This value should be set 
before allocating the structure. 

ari_arguments_count 

is the maximum number of arguments in the arguments array. This value should 
be set before allocating the structure. 
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Name: execute epilogue 

The execute_epilogue_ subroutine is called during process or run unit termination to 
call the routines in the list of epilogue handlers. The logout and new_proc commands 
are the prime callers of execute_epilogue_. It is also called when the run unit 
terminates to allow programs executing in the run unit to clean up. The 
add_epilogue_handler_ subroutine is used to add a program to the list that 
execute_epilogue_ calls. 

USAGE 

declare execute_epi logue_ entry (bit (1) aligned); 

call execute_epi logue_ (run_only) ; 

ARGUMENTS 

run_only 

is set to "l"b if epilogue handlers are to be invoked only for the run unit and 
not for the entire process. (Input) 



Name: expand pathname 

The expand_pathname_ subroutine is used to convert a relative or absolute pathname 
into a directory name and entryname. 

Entry: expand pathname 

USAGE 

del expand_pathname_ entry (char (*) , char (*) , char (*) , fixed bin (35)); 
call expand_pathname_ (pathname, dirname, entryname, code); 
ARGUMENTS 
pathname 

is the relative or absolute pathname to be expanded. (Input) 
dirname 

is the directory portion of the expanded pathname. (Output) 
entryname 

is the entryname portion of the expanded pathname. (Output) 
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code 

is a standard system error code. (Output) It can have one of the following 
values: 

error_table_$lesserr 

too many less-than characters ("<") in pathname. 
error_table_$badpath 

invalid syntax in pathname. 
error_table_$pathlong 

the expanded pathname is longer than 168 characters. 
error_table_$entlong 

the entryname of the expanded pathname is longer than 32 characters. 
error_table_$no_wdir 

a relative pathname is specified, but no working directory is in force for the 

process. 

error_table_$archive_pathname 

the input pathname specified an archive component 

NOTES 

This entry does not accept the syntax for specifying archive component pathnames: if 
one is supplied, an error code is returned. See the information on Constructing and 
interpreting names in the Programmer's Reference Manual for details. 

For compatibility with older programs, if pathname is given as a null string, the 
working directory is used. 



Entry: expand pathname $add suffix 

This entrypoint expands a relative or absolute pathname into a directory name and 
entryname portion, adding a suffix to the entryname if tnat suffix is not already 
present. 

USAGE 

del expand_pathname_$add_suf f i x entry (char (*) , char (*) , char (*) , 
char (*) , fixed bin (35)); 

call expand_pathname_$add_suf f ix (pathname, suffix, dirname. entryname, 
code) ; 

ARGUMENTS 

pathname 

is the relative or absolute pathname to be expanded. (Input) 
suffix 

is the suffix to be added to the entryname. (Input) The period separating the 
entryname and the suffix should not be included. If a null string is supplied, no 
suffix is added. 
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dirname 

is the directory portion of the expanded pathname. (Output) 
entryname 

is the entryname portion of the expanded pathname. (Output) 

code 

is a standard system error code. (Output) It can have the same values described 
for expand_pathname_. 



Entry: expand pathname {component 

This entrypoint expands a relative or "absolute pathname into a directory name, an 
archive name, and an archive component portion, or into a directory name and 
entryname portion if no component name is present. 

USAGE 

del expand_pathname_$component entry (char («) , char (*) , char (*) , 
char (") , fixed bin (35)); 

call expand_pathname_$component (pathname, dirname, entryname, 
componentname, code) ; 

ARGUMENTS 

pathname 

is the relative or absolute pathname to be expanded. (Input) 
dirname 

is the directory name portion of the expanded pathname. (Output) 
entryname 

if the input pathname specifies an archive component, this is the entryname of 
the archive (with the archive suffix added). (Output) Otherwise, this is the 
entryname portion of the input pathname. 

componentname 

if the input pathname specifies an archive component, this is the component 
name. (Output) Otherwise, this is the null string. 

code 

is a standard system error code. (Output) It can have the same values as for 
expand_pathname_ except for error_table_$archive_pathname. 
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Entry: expand pathname ^component add suffix 

This entrypoint expands a relative or absolute pathname into a directory name, an 
entryname, and an archive component name. The specified suffix is added either to 
the entryname or component name, as appropriate, if it is not already present. 

USAGE 

del expand_pathname_$component_add_suf f i x entry (char («) , char («) , 
char (*) , char (*) , char («) , fixed bin (35)); 

call expand_pathname_$component (pathname, suffix, dirname, entryname, 
componentname, code) ; 

ARGUMENTS 

pathname 

is the relative or absolute pathname to be expanded. (Input) 
suffix 

is the suffix to be added to the component name or entryname. (Input) The 
period separating the entryname and the suffix should not be included. If a null 
string is supplied, no suffix is added. 

dirname 

is the directory name portion of the expanded pathname. (Output) 
entryname 

if the input pathname specifies an archive component, this is the entryname of 
the archive (with the archive suffix added). (Output) Otherwise, this is the 
entryname portion of the input pathname, with the specified suffix added if it is 
not already present. 

componentname 

if the input pathname specifies an archive component, this is the component 
name, with the specified suffix added if it is not already present. (Output) 
Otherwise, this is the null string. 

code 

is a standard system error code. (Output) It can have the same values as for the 
expand_pathname_$component entry. 
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Name: exponent control 

The exponent_control_ entry points provide control over the behavior of the system in 
the event of a computational overflow or underflow. The normal behavior of the 
system in both cases is to signal a fault condition. (See the Programmer's Reference 
Manual for more information on conditions and other unusual events). These entry 
points provide the option of transparently restarting these faults with a known result: 
zero in the case of an underflow; a user-settable value in the case of an overflow. 
By default, this value is the largest represen table floating point number. 

This subroutine affects the system's handling of exponent overflow or underflow only 
when the overflow or underflow condition is raised. In certain cases, the error 
condition is raised instead. This subroutine does not affect the system's handling of 
these cases. 

Entries: exponent control $f ault overflow, exponent control $f ault underflow 

These entrypoints instruct the system to signal fault conditions when computations 
overflow or underflow. 

USAGE 

del exponent_control_$f aul t_overf low entry (fixed bin (35)); 
del exponent_control_$f aul t_underf low entry (fixed bin (35)); 

call exponent_control_$f au 1 t_overf 1 ow (code); 
call exponent_control_$f aul t_underf low (code); 

ARGUMENTS 

code 

is a standard system status code. (Output) 

Entries: exponent control $restart overflow, 

exponent control Srestart underflow 

These entrypoints instruct the system to automatically restart overflow and underflow 
conditions, respectively. In the overflow case, the default value for the result of the 
computation is used for positive overflows. If the overflow is in a negative direction, 
the negative of the default value is used. 

USAGE 

del exponent_control_$restart_overf low entry (fixed bin (35)); 
del exponent_control_$restart_underf 1 ow entry (fixed bin (35) ) » 

call exponent_control_$restart_overf low (code); 
call exponent_control_$restart_underf low (code); 
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ARGUMENTS 
code 

is a standard system status code. (Output) 



Entry: exponent control $restart overflow value 

This entry point instructs the system to automatically restart overflow conditions, and 
specifies a value to be returned as the computational result 

USAGE 

del exponent_control_$restart_overf low_value entry (float bin (63). 
fixed bin (35)) ; 

call exponent_control__$restar t_overf low_val ue (amax_val ue, code); 

ARGUMENTS 

amax_value 

is the value to be supplied for the result of computations that result in overflows. 
(Input) 

code 

is a standard system status code. (Output) 



Name: file manager 

The file_manager_ subroutine is the interface between the data storage and retrieval 
services of data management and Multics file access and control mechanisms. It also 
ensures concurrency and recovery protection by invoking data management integrity 
services when protected data management (DM) files are accessed or modified. 

As a direct user interface, the file_manager_ subroutine makes the protection and 
recovery capabilities of integrity services available to users who write applications using 
their own data storage and retrieval software. 

See the section entitled "Multics Data Management" in the Multics Programmer's 
Reference Manual, Order No. AG91, for a complete description of data storage and 
retrieval services, integrity services, and DM files. 



2-250 



AG93-05 



file_manager_ file_manager_ 



Entry: file manager Sclose 

This entry point closes a DM file in the current process. The file to be closed is 
designated by its opening identifier. 

USAGE 

declare f i le_manager_$close entry (bit (36) aligned, fixed bin (35)); 

call f i 1 e_manager_$c 1 ose (oid, code); 

ARGUMENTS 

oid 

is the file opening identifier of the file to be closed. (Input/Output) It is set to 
zero by this entry point in order to indicate that it is no longer valid. 

code 

is a standard status code. (Output) 
NOTES 

If the file is opened more than once in the process, this operation decreases the 
number of openings by one. See the description of the open entry for more details. 

The user process does not have to be in transaction mode to close a DM file. 
Aborting a transaction does not cause the file to be reopened, even if it was closed 
by a delete_c!ose operation and the deletion was rolled back. 



Entry: file manager $create 

This entry point creates a DM file. The caller specifies its pathname and attributes, 
and must specify whether the file is protected; see "Notes" below. 

USAGE 

declare f i 1 e_manager_$create (char (*) , char (*) , ptr, fixed bin (35)); 

call f i le_manager_$create (dir_path, entry_name, f i 1 e_create_i nf o_ptr , 
code) ; 

ARGUMENTS 

dir_path 

is the absolute pathname of a directory. (Input) The file will be added to this 
directory. 

entry_name 

is the name of the file. (Input) 
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f ile_create_inf o_ptr 

points to the file_create_info structure (see below). (Input) If this pointer is null, 
a protected file is created with the default attribute values. 



code 

is a standard status code. (Output) 



ACCESS REQUIRED 



You cannot create a DM file in your home directory unless you have the proper 
access to the directory above the containing directory, and, in any event, you must 
have sufficient access to add an entry to the containing directory. The file is created 
with read and write access for the caller and the DM daemon (Data_Management.Daemon). 



NOTES 

In the current implementation, file attributes specified in the file_create_info structure 
such as ring brackets and blocking factor cannot be changed. 

STRUCTURE 



Following is the structure used to describe the attributes to assign to a file being 
created. It is declared in dm_file_create_info.incl.pll. 

del 1 f i 1 e_create_i nf o aligned based (f i 1 e__create_i nf o_ptr) , 

2 version char (8) aligned, 

2 c i_s i ze_i njbytes fixed bin (35) » 

2 blocki ng_f actor fixed bin, 

2 f 1 ags unal , 

3 protected bit (1) unal, 

3 no_concurrency bit (1) unal, 

3 no_rollback bit (1) unal, 

3 mbz_l bit (15) unal , 

2 r i ng_brackets (2) fixed bin (3) unal, 

•2 mb2_3 bit (10) unal , 

2 mbz_2 (30) fixed bin (71) ; 



STRUCTURE ELEMENTS 



version 

must be set by the caller to FILE_CREATE_INFO_VERSION_2. This permits 
upward compatible changes to this structure. 

ci_size_in_bytes 

is the control interval size. Currently the only size available is 4096. If this item 
is zero, a default value is used. Currently the default value is 4096. 
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blocking_f actor 

tells the file manager how to allocate disk storage. In the current implementation 
this is interpreted as the number of control intervals to put in each segment, and 
only 64 and 255 are allowed. If this item is zero, a default value is used. The 
current default value is 255. 

flags.protected 

determines whether the file is protected from transaction failure and from 
concurrent access by other processes. If the protected bit is on, get, put, and 
allocate operations are permitted only in transaction mode. Create and delete 
operations are protected regardless of whether the process is in a transaction. If 
this bit is off, the file is unprotected, which means that the file and its contents 
may be damaged by concurrent access or transaction failure. An unprotected file 
may be accessed within or without a transaction. Accessing a protected file is 
substantially more expensive than accessing an unprotected file. The default is to 
provide protection. 

flags. no_concurrency 

turns off protection against concurrent access by other processes. Concurrency 
protection is implemented by locking each control interval that is accessed. The 
get operation locks in share mode. All other operations lock in exclusive mode. 
Create and delete lock the entire file in exclusive mode. Locking is expensive. 
This bit turns it off if it is not needed. If protection is off, this bit is ignored. 
The default is to provide concurrent access protection. 

flags.no_rollback 

turns off protection against transaction failure. Protection against transaction 
failure is implemented by journaling a before image of each modification. When 
a transaction fails, its modifications are undone by restoring these before images. 
Journaling is expensive. This bit turns it off if it is not needed. If protection is 
off, this bit is ignored. The default is to provide protection from transaction 
failure. 

ring_brackets 

are the extended ring brackets of the file. They specify the range of rings from 
which the file may be accessed. The first is the write bracket. It's value cannot 
be less than the data management ring (loosely, the ring of execution of the 
file_manager_) or the validation level of the creating process. The second is the 
read bracket. It's value cannot be less than the write bracket. The default for 
both ring brackets is the validation level of the calling process. 

mbz_l, mbz_2, mbz_3 

must be initialized to zero by the caller. This is so that upward compatible 
changes will be able to assume that existing programs put zeros in these areas. 
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Entry: file manager Screate open 

Calling this entry point has the effect of calling the create and open entries, but is 
more efficient. If the file already exists, it is opened and code is 
dm_error_$file_already_exists. If the file already exists and is already open, the 
opening identifier is returned and code is dm_error_$file_already_open. 

USAGE 

declare f i 1 e_manager_$create_open entry (char (*) , char (*) , ptr, bit (36) 
aligned, fixed bin (35)); 

call f i 1 e_manager_$create_open (dir_path, entry_name, 
f i le_create_i nfo_ptr , oid, code); 

ARGUMENTS 

dir_path 

is the absolute pathname of a directory, (Input) The file is added to this 
directory. 

entry_name 

is the name of the file. (Input) 

f ile_create_inf o_ptr 

is a pointer to a file_create_info structure into which the file attributes are to be 
placed. (Input) This structure may in turn be used to create a new DM file into 
which to copy the old DM file. The structure is defined in dm_fm_create_info.incl.pll. 
(See the create entry for a description of this include file). 

oid 

is the opening identifier assigned to the file. (Output) If it is not zero, the oid 
is valid and can be used, regardless of the value of code. If the transaction 
aborts and the file is deleted, it still needs to be closed, since openings are not 
undone by rollback. 

code 

is a standard status code. (Output) If it is dm_error_$file_already_exists or 
dm_error_$file_already_open, the operation is considered successful and oid is 
usable. 
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Entry: file manager $deletc close 

Calling this entry point has the same effect as calling the delete and close entries, but 
is more efficient. It deletes a file that is already open. 

USAGE 

declare f i le_manager_$delete_close entry (bit (36) aligned, fixed 
bin(35)); 

call f i le_manager_$del ete_close (oid, code); 

ARGUMENTS 

oid 

is the file opening identifier of the file to be deleted and closed. (Input/Output) 
It is set to zero by this entry point in order to indicate that it is no longer 
valid. The file remains closed even if the transaction is aborted, negating the 
delete operation. 

code 

is a standard status code. (Output) 



Entry: file manager Sfree 

This entry point frees disk space allocated to control intervals. The set of consecutive 
control intervals is specified by the number of the first control interval and the 
number of consecutive control intervals starting at the first one. After the disk space 
for a control interval has been freed, its content is effectively zero. This operation 
has a high fixed overhead, so it should not be called for one control interval at a 
time. 

If any or all of the control intervals are already free, code is set to 
dm_error_$ci_already_free. The operation is, nevertheless, successful. 

USAGE 

declare f i 1 e_manager_$f ree entry (bit (36) aligned, fixed bin(27)» fixed 
bin (27) , fixed bin (35)) ; 

call f i 1 e_manager_$f ree (oid, first_ci, n_ci, code); 
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ARGUMENTS 
oid 

is a file opening identifier. (Input) 
first_ci 

is the control interval number of the first control interval of the set whose 
physical space is to be freed. (Input) 

n_ci 

is the number of consecutive control intervals whose physical space is to be freed. 
(Input) 

code 

is a standard status code. (Output) If it is dm_error_$ci_already_free, the 
operation can still be considered a success. 

ACCESS REQUIRED 

The user must have write access to the file. 
NOTES 

If the file is protected, the caller must be in transaction mode and the free operation 
is done under the auspices of the integrity services. If the transaction aborts, the 
control intervals are reallocated and their contents restored. 



Entry: file manager $get 

This entry point reads data from a control interval. The caller may specify one or 
several parts. Each part is described by its byte offset relative to the beginning of 
the addressable portion of the control interval and its length in bytes. Each part has 
a pointer to a buffer provided by the caller. 

If the control interval does not exist, the buffers provided by the caller are filled 
with zeros and code is set to zero. 

USAGE 

declare f i 1 e_manager_$get entry (bit (36) aligned, fixed bin (27), ptr, 
fixed bin (35)) ; 

call f i 1 e_manager_$get (oid, ci_num, ci_parts_ptr , code); 
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ARGUMENTS 



oid 

is a file opening identifier. (Input) 
ci_num 

is a control interval number. (Input) 



ci_parts_ptr 

points to the ci_parts structure declared in dm_ci_parts.incl.pll. (Input) (See 
below) 



code 

is a standard status code. (Output) 



NOTES 



If the file is protected, the process must be in transaction mode, and unless 
no_concurrency is specified, get locks the control interval in share mode. It is kept 
locked until the end of the transaction. This assures that no other transaction can put 
anything into the control interval, free it, or delete the file during the current 
transaction. If the control interval is locked in exclusive mode by another transaction, 
get waits until it finishes. If waiting is pointless because the current transaction is 
deadlocked with another transaction, the transaction_deadlock condition is signaled. 



ACCESS REQUIRED 



The calling process must have read access to call the get entry. 



STRUCTURE 



The ci_parts structure defines the parts of a control interval and is declared in 
dm_ci_parts.incl.pll. 



del 1 c i_parts 

2 number_of_par ts 
2 part 

3 of f set_i n_bytes 
3 1 ength_i n__bytes 
3 local_ptr 



aligned based (c i_par ts_ptr) , 
fixed bin, 

(c i p_number_of_par ts 
refer (c i_parts . number_of_par ts) ) , 
fixed bin, 
fixed bin, 
ptr; 



STRUCTURE ELEMENTS 



number_of_parts 

is the number of parts. Zero is legal and there is currently no limit on the 
number of parts. 
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offset_in_bytes 

is the offset of the part within the addressable portion of the control interval. It 
is the zero relative index of the first byte of the part. It is the number of bytes 
that are to be skipped, starting at the beginning of the addressable portion. 

The addressable portion of a control interval begins with the first byte after the 
four word header and ends with the last byte before the two word trailer. The 
only exception is control interval zero. It has a smaller addressable portion, 
because the file attributes are stored in it. 



The length of the addressable portion is 4072 bytes. Control interval zero has 
3176 bytes. Constants for these values are declared in dm_ci_lengths.incl.pll. 

length_in_bytes 

is the number of bytes in the part If it is zero, the part is ignored. 
local_ptr 

is a pointer to the buffer provided by the caller for the part. 



Entry: file manager $get ci header 

This entry reads the 4- word control interval header (the structure appears below). The 
header tells whether a control interval is allocated when it was last modified, and 
what the unique identifier of the DM file is. 

Protection and access are the same as for the get entry. 

If the control interval does not exist, this entry returns the header that it would have 

had. with zero in the time .modified field and code set to zero, Tt does not create 
the control interval. 

USAGE 

declare f i 1 e_manager_$get_c i_header entry (bit (36) aligned, fixed 
bin (27). 1 like ci_header aligned, fixed bin (35)); 

call f i 1 e_manager_$get_c i_header (oid, ci_num, ci_header, code); 

ARGUMENTS 

oid 

is a file opening identifier. (Input) 
ci_num 

is a control interval number. (Input) 
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cijieader 

is the cijieader structure, declared in dm_ci_header.incl.pll. (Input/Output) (See 
below) 

code 

is a standard status code. (Output) 
STRUCTURE 

The ci_header structure is in dm_ci_header.incl.pll. 

del 1 ci_header aligned based (ci_header_ptr) , 
2 stamp, 

3 version bit (9) unal , 

3 bj_idx fixed bin (9) uns una], 

3 t i me_mod i f i ed fixed bin (53) unal, 
2 id, 

3 uid bit (36) unal , 
3 s i ze_code 

k exponent fixed bin (6) uns, 

k addon fixed bin (3) uns, 

3 num fixed bin (27) uns unal; 

STRUCTURE ELEMENTS 

version 

is the version of the structure, currently CI_HEADER_STAMP_VERSION_l. 
bj_idx 

is used to synchronize control interval writes with before journal writes. 
time_modified 

is the Multics clock time when this control interval was last modified. If the 
control interval does not exist, this item is zero. 

uid 

is the unique identifier of the data management file. It is not the Multics file 
system uid. 

size_code 

gives the physical size of the control interval which includes the header and 
trailer. The size in bytes = (64 + 8 * addon) * 2**exponent. 

num 

is the control interval number. The number of the first control interval is zero. 
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Entry: file manager $get_ci__ptr 

This entry point returns a pointer to the addressable portion of a control interval. 
Pointers to control intervals should be used only in well defined and contained 
situations to enhance the performance of accessing data in a control interval for 
retrieval purposes. This entry is helpful when it is known beforehand that several 
pieces of data are to be read from the same control interval, but they cannot be read 
by specifying several parts to the get entry (e.g., the offset of one is dependent on 
the value of another). Unlike other entries which get data, it is not valid to get a 
control interval pointer to a control interval that is not allocated. 

USAGE 

declare f i 1 e_manager_$get_c i_ptr entry (bit (36) aligned, fixed bin (27), 
ptr , f i xed bin (35) ) ; 

call f i 1 e_manager_$get_c i_ptr (oid, ci_num, ci_ptr, code); 

ARGUMENTS 

oid 

is a file opening identifier. (Input) 
ci_num 

is a control interval number. (Input) 
ci_ptr 

points to the addressable portion of the control interval. (Input /Output) The 
addressable portion begins immediately after the control interval header. A null 
value is returned for this pointer if there is a error and the returned code is not 
zero. 

code 

is a standard status code. (Output) It can be dm_error_$ci_not_allocated if the 
specified control interval has not been allocated. ci_ptr is set to null. 
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NOTES 

In order to make it possible to look at control intervals via a pointer, the create 
entry sets the ring brackets on file components to: 

<DM-ri ng>,<val idation-level>,<val idation-level>. 

If the file is protected, the process must be in transaction mode, and unless 
no_concurrency is specified, get_ci_ptr locks the control interval in share mode. It is 
kept locked until the end of the transaction. This assures that no other transaction 
can put anything into the control interval, free it, or delete the file during the 
current transaction. If the control interval is locked in exclusive mode by another 
transaction, get_ci_ptr waits until it finishes. If waiting is pointless because the current 
transaction is deadlocked with another transaction, the transaction_deadlock condition is 
signaled. 

If the control interval does not exist, an error code of value dm_error_$ci_not_allocated 
is returned. 

ACCESS REQUIRED 

The calling process must have read access to call the get_ci_ptr entry. 



Entry: file manager $get exclusive 

This entry point is the same as get entry except that it locks the control interval 
exclusively, preventing other transactions from even obtaining the share lock necessary 
to do a normal get operation. 

USAGE 

declare f i 1 e_manager_$get_exc 1 us i ve entry (bit (36) aligned, fixed 
bin (27), ptr, fixed bin (35)); 

call f i 1 e_manager_$get_exc 1 us i ve (oid, ci_num, c i_parts_ptr , code); 

ARGUMENTS 

oid 

is a file opening identifier. (Input) 
ci_num 

is a control interval number. (Input) 
ci_parts_ptr 

points to the ci_parts structure declared in dm_ci_parts.incl.pll. (Input) See the 
get entry. 
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code 

is a standard status code. (Output) 
NOTES 

This entry is useful for applications that are going to do a put operation into the 
same control interval. 

Obtaining an exclusive lock on a control interval effectively reduces concurrency, so 
this entry should be used advisedly. 



Entry: file__manager $get stream 

This entry point returns a specified number of bytes from a DM file, given an 
opening identifier, a file offset, and a buffer in which to place the bytes. This entry 
treats the DM file as a stream of bytes consisting of the concatenation of the 
addressable portion of all control intervals in the DM file. 

i » <-» *r>r 
L/O/HUC 

declare f i 1 e_manager_$get_stream entry (bit (3&) aligned, fixed bin^S), 
ptr , f ixed bi n (21) ) ; 

call f i 1 e_manager_$get_stream (oid, f i 1 e_of f set_i n_bytes , buf_ptr, 
buf_l ength_i n_bytes) ; 

ARGUMENTS 

oid 

is the opening identifier of the DM file to be read from. (Input) 
f ile_of f set_in_by tes 

is the offset given in bytes, from the beginning of the logical address space of 
the DM file given in bytes with an offset of zero representing the beginning of 
the file. (Input) 

buf_ptr 

is a pointer to a buffer where the bytes read from the DM file may be placed. 
(Input) 

buf_length_in_bytes 

is the number of bytes that are to be read from the DM file. (Input) 
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NOTES 

If the DM file is protected, the process must be in transaction mode and unless 
concurrency is specified, get_stream locks in share mode the control intervals in which 
the specified stream of bytes resides. 

ACCESS REQUIRED 

The calling process must have read access to the DM file to call the get_stream entry. 



Entry: file manager Slock advice 

This entry point permits applications to give the file manager advice about locking 
granularity. For example, if an application is to modify every control interval in a 
file, it can request the file manager to lock the entire file and save the overhead of 
locking individual control intervals. 

USAGE 

declare f i 1 e_manager_$ 1 ock_advi ce entry (bit (36) aligned, fixed bin, 
fixed bin (35)) ; 

call f i 1 e_manager_$ 1 ock_adv i ce (oid, lock_mode, code); 
ARGUMENTS 

Old 

is a file opening identifier. (Input) 
lock_mode 

is the finest and weakest lock mode to use on this file for the remainder of the 
opening. (Input) It must be one of the five following modes: 4 (LOCK_MODE_IS), 
5 (LOCK_MODE_IX), 6 (LOCK_MODE_SIX), 2 (LOCK_MODE_S), or 3 
(LOCK_MODE_X) which are declared in dm_lock_modes.incl.pll. 
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LOCK MODE NAMES 

Named constants for the lock modes are provided in the include file dm_lock_modes.incl.pll 

del LOCK_MODE_S fixed bin static options (constant) init (2) 

del LOCK_MODE_X fixed bin static options (constant) init (3) 

del LOCK_MODE_IS fixed bin static options (constant) init (k) 

del LOCK__MODE_i X fixed bin static options (constant) init (5) 

del LOCK_MODE_S I X fixed bin static options (constant) init (6) 

del LOCK_ENT I RE_F I LE fixed bin {2k) static options (constant) init (-1); 

del LOCK_MODE_NAMES (2:6) char (3) int static options (constant) 

init ("S", "X", "IS", "IX", "SIX") ; 



S Share 

Let others read it but not modify it. 

X Exclusive 

Let nobody else read or modify it. 

IS Intend Share 

I am only using S locks, because I am only reading CIs. 

IX Intend Exclusive 

I am using S and X locks, because I am reading and modifying CIs. 

SIX Share with Intend Exclusive 

I am reading control intervals, but only locking the ones 1 modify 



code 

is a standard status code. (Output) 
NOTES 

Lock advice never abridges protection against concurrent file access by other processes. 
If no lock advice is given, file manager uses the weakest lock necessary to provide 
concurrency protection, and the finest granularity available, which is the control 
interval. Lock advice always causes file manager to use a stronger lock or coarser 
granularity than absolutely necessary. This reduces concurrency in order to reduce 
locking overhead. 
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Lock advice applies to protected files unless the no_concurrency attribute is present 
Since it is an attribute of the opening and not of the file, it can be given to any 
open file, regardless of whether a transaction is in progress. The first time the file is 
referenced in each transaction, the advice tells the file manager what kind of a global 
file lock to acquire. If the lock advice is given after the first time the file is 
referenced, it will not be used until the next transaction. The lock advice is retained 
until it is changed, or the file is closed. 

The advice concerns the type of lock to use at the file level. The only way to 
control the type of lock used on a control interval is to call get_exclusive instead of 
get. If no advice is given, IS (intention shared) is presumed. IS is strong enough for 
get and get_ci_header which lock control intervals in S (share) mode. Put, allocate, 
and free require that the file lock be upgraded to the stronger IX (intention exclusive) 
mode, because they lock control intervals in X (exclusive) mode. Create and delete 
lock the file in X mode, regardless. If advice is given, then all operations lock the 
file in the advised mode unless it is too weak for the operation. The SIX (shared and 
intention exclusive) mode means only lock the control intervals that are modified. SIX 
saves the overhead of locking individual control intervals for get operations because it 
prevents other transactions from getting anything but an IS lock on the file. 



Entry: file manager $open 

This entry point makes a DM file accessible within a process. The file is specified by 
its pathname. The file is assigned an opening identifier in the current process, by 
which it is designated in all subsequent calls to file_manager_. 

USAGE 

declare f i 1 e_manager_$open entry (char (*) , char (*) , bit (36) aligned, 
fixed bin (35)) ; 

call f i 1 e_manager_$open (dir_path, entry_name, oid, code); 

ARGUMENTS 

dir_path 

is the absolute pathname of the directory which contains the file. (Input) 

entry_name 

is the entry name of the file. (Input) 

oid 

is the file opening identifier assigned to the file and returned to the caller. 
(Output) If it is not zero, it is usable, regardless of code. 

code 

is a standard status code. (Output) If it is dm_error_$file_already_open, the 
operation is considered successful and oid is usable. 
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NOTES 

If the file was already opened in the current process, the open entry does not assign 
a new opening identifier, but rather returns the opening identifier that was already 
assigned and sets code to dm_error_$file_already_open. The file manager keeps track 
of the number of opens and closes. The opening identifier remains valid as long as 
there are more opens than closes. If all subsystems within a process close a file the 
same number of times they open it, they will not invalidate each others openings. 

There is no requirement for the process to be in transaction mode when opening a 
file, protected or not. Aborting a transaction has no effect on file openings, even if 
create_open was called and the create is rolled back. Attempts to use such an opening 
will result in dm_error_$file_doesnt_exist. The same thing happens if a file is opened 
and then deleted. Close is the only operation allowed on a file which has been 
deleted. 



Entry: file manager $put 

This entry point writes data into a control interval. The caller can specify one or 
several parts of the control interval to be written. 

If the control interval does not exist, it is automatically allocated and the content of 
its addressable portion is initialized to zero. 

USAGE 

declare f i 1 e_manager_$put entry (bit (36) aligned, fixed bin(27)» ptr, 
fixed bin (35)) ; 

caii f i "ie_manager$put (oia, ci_num, c i_parts_ptr , code^ ; 

ARGUMENTS 

oid 

is a file opening identifier. (Input) 
ci_num 

is a control interval number. (Input) 
ci_parts_ptr - 

points to the ci_parts structure declared in dm_ci_parts.incl.pll. (Input) (See the 
get entry.) 

code 

is a standard status code. (Output) 
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NOTES 

If the file is protected, the process must be in transaction mode, and unless 
no_concurrency is specified, put locks the control interval in exclusive mode. It is 
kept locked until the end of the transaction. This assures that no other transaction 
can put anything into the control interval, get anything from it, free it, or delete the 
file during the current transaction. If the control interval is locked by another 
transaction, the put operation must wait until it finishes. If waiting is pointless 
because the current transaction is deadlocked with another transaction, the 
transaction_deadlock condition is signaled. 

Unless the file is unprotected or has the no_rollback attribute, a put operation causes 
a before image of data in the control interval to be journalized before actually 
modifying it. If the transaction should abort, the before journal manager will undo its 
modifications by restoring the before images. 

The modified control interval can not be written to disk until its before image is on 
disk, because there must be enough information on disk to roll back the transaction 
even if main memory fails. If the modified control interval were written first and the 
system failed before the transaction finished and the content of main memory could 
not be flushed to disk, the modification could not be undone and rollback of the 
transaction would be incomplete. The data management system holds modified control 
intervals in main memory until the associated before images are written to disk. The 
Multics clock value in the control interval header is used for this purpose. 

The put request is rejected if either of the following is true: 

- The user does not have write permission on the file. 

- ihe file is protected but the process is not in a transaction mode. 



Entry: file_manager $put stream 

This entry point writes a specified number of bytes in a DM file at a given offset in 
the logical address space. This entry treats the DM file as a stream of bytes made up 
of the concatenation of the addressable portion of all control intervals in the DM 
file. 

USAGE 

declare f i 1 e_manager_$put_stream entry (bit (36) aligned, fixed bin (48), 
ptr, fixed bin (21), fixed bin (35)); 

call f i 1 e_manager_$put (oid, f i le_of f set_i n_bytes, buf_ptr, 
buf_length_i n_bytes, code); 
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ARGUMENTS 
oid 

is the opening identifier of the DM file. (Input) 
file_offset_in_bytes 

is the offset in bytes into the logical address space of the DM file where the 
supplied bytes will be placed. (Input) 

buf_ptr 

is a pointer to the buffer containing the bytes to be written to the DM file. 
(Input) 

buf_length_in_bytes 

is the number of bytes to be written into the DM file from the buffer. (Input) 

code 

is a standard system status code. (Input) 
NOTES 

If the DM file is protected, the process must be in transaction mode, and unless 
concurrency is specified, put_stream locks the control intervals in which the specified 
stream of bytes resides. 

ACCESS REQUIRED 

The calling process must have write access to the DM file to call the put_stream 
entry. 



Entry: file manager $raw get 

This entry point resembles the get entry, except that it treats the file as if it were 
unprotected. It does not require that the process be in transaction mode. 

USAGE 

declare f i 1 e_manager_$raw_get entry (bit (36) aligned, fixed bin (27), 
ptr, fixed bin (35) ) ; 

call f i 1 ejnanager_$raw_get (oid, ci_num, c i_par ts_ptr , code); 

ARGUMENTS 

oid 

is a file opening identifier. (Input) 
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ci_num 

is a control interval number. (Input) 
ci_parts_ptr 

points to a ci_parts structure declared in dm_ci_parts.incl.pll. (Input) (See the get 
entry.) 

code 

is a standard status code. (Output) 



Entry: file manager Sraw put 

This entry point resembles the put entry, except that it treats the file as if it were 
unprotected. Also, the time_modified stamp in the control interval header is not 
updated. This operation is intended for applications that need to update protected files 
in an unprotected manner. It does not require that the process be in transaction 
mode. 

USAGE 

declare f i 1 e_manager_$raw_put entry (bit (36) aligned, fixed bin (27). 
ptr , f i xed b i n (35) ) ; 

call f i 1 e_manager_$raw_put (oid, ci_num, c i_par ts_ptr , code); 

ARGUMENTS 

oid 

is a file opening identifier. (Input) 
ci_num 

is a control interval number. (Input) 
ci_parts_ptr 

points to a ci_parts structure declared in dm_ci_parts.incl.pll. (Input) (See the get 
entry.) 

code 

is a standard status code. (Output) 
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Entry: file manager $simple__get 

This entry point is used to get a sequence of bytes from a DM file, given an opening 
identifier, a control interval number, and control interval offset. The sequence is 
placed in a caller-supplied buffer. This entry point differs from the get entry in that 
it can only get bytes from one location within a control interval, and a ci_parts 
structure does not have to exist to make the call. 

USAGE 

declare f i 1 e_manager_$s impl e_get entry (bit (36) aligned, fixed bin(27), 
fixed bin(21), ptr, fixed bin(21)); 

call f i 1 e_manager_$s impl e_get (oid, ci_num, c i_of f set_i n_bytes , buf_ptr, 
buf_l ength_i n_bytes) ; 

ARGUMENTS 

oid 

is the opening identifier of the DM file, (Input) 
ci_num 

is the control interval in the DM file that contains the data to be fetched. 
(Input) 

ci_of f set_in_by tes 

is the offset from the beginning of the control interval to the beginning of the 
data, expressed in bytes. (Input) 

buf_ptr 

is a pointer to a caller supplied buffer where the data is to be placed. (Input) 
buf_length_in_bytes 

is the length in bytes of the caller supplied buffer. (Input) This also specifies the 
number of bytes to be fetched. The sum of ci_offset_in_bytes and buf_length_in_bytes 
must not exceed the length of a control interval. 

code 

is a standard system status code. (Output) 
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Entry: file manager Ssimple put 

This entry point places a given sequence of bytes into a DM file, given an open id, a 
control interval number, and a control interval offset. This entry differs from the put 
entry point in that it places bytes only at one given location within a control interval, 
so no ci_parts structure is required. 

USAGE 

declare f i 1 e_manager_$s impl e_put entry (bit (36) aligned, fixed bin (27), 
fixed b i n (2 1) , ptr, fixed bin(21)); 

call f i le_manager_$simple_put (oid, ci_num, c i_of f set_i n_bytes , buf_ptr, 
buf_l ength_i n_bytes) ; 

ARGUMENTS 

oid 

is the opening identifier of the DM file. (Input) 
ci_num 

is the control interval in the DM file where the data is to be placed. (Input) 
ci_of f set_in_by tes 

is the offset from the beginning of the control interval to the beginning of where 
the data is to be placed. (Input) 

buf_ptr 

is a pointer to the buffer containing the data. (Input) 

buf_length_in_bytes 

is the number of bytes that are to be placed into the DM file. (Input) 

code 

is a standard system status code. (Output) 



Entry: file manager Sstatus 

This entry point returns status information on a DM file. 
USAGE 

declare f i 1 e_manager_$status entry (bit (36), ptr, fixed bin (35)); 
call f i le_manager_$status (oid, f i 1 e_status_ptr , code); 
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ARGUMENTS 
oid 

is the opening identifier of the DM file. (Input) 
file_status_ptr 

is a pointer to a file_status structure to be filled in by this entry. (Input) See 
the dm_file_status structure described below. 

code 

is a standard system status code. (Output) 
STRUCTURE 

This structure lists the information returned by file_manager_$status to describe a DM 
file. It resides in the include file dm_file_status.incl.pll. 

del 1 dm_f i le_status aligned based (dm_f i 1 e_status_ptr) , 
2 version char (8) unaligned, 
2 fmuniquei d bit (36) aligned, 
2 mode bit (36) aligned, 
2 date_t ime_created fixed bin (71)* 
2 r i ng_brackets (2) fixed bin (3), 
2 switches, 
3 (protected_sw, 

no_concur rency_sw, 
no_rol lback_sw) bit (1) unaligned, 
3 padl bit (33) unaligned, 
2 highest_ci fixed bin (18) , 
2 ci_size fixed bin (18) , 
2 pad (5) f i xed Din; 

STRUCTURE ELEMENTS 

version 

is the current version of the structure, DM_FILE_STATUS_VERSION_l. 
fm_unique_id 

is the file manager unique identifier (fmuid) of the file, which uniquely identifies 
it to data management 

mode 

is the user's effective access to the file, taking into consideration the extended 
access (access available via data management operations) and AIM. 

date_time_created 

is the date-time the file was created, 

ring_brackets 

are the extended ring brackets of the file as implemented by data Management 
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protected_sw 

if ON, data management transactions are required in order to reference the file's 
data. 

■ no_concurrency_sw 

if ON, only one process can reference the file at a time. 

no_rollback_sw 

if ON, the rollback operation is not allowed. 

highest_ci 

is the sequential number of the highest control interval allocated in the file. 
ci_size 

is the number of bytes per control interval. 



Entry: file manager Sterminate ci ptr 

This entry point releases a control interval pointer to a specific control interval of a 
DM file retrieved through the get_ci_ptr entry point This entry must be called for 
each call to get_ci_ptr. 

USAGE 

declare f i 1 e_manager_$termi nate__c i_ptr entry (bit (36) aligned, 
fixed bin (27), ptr, fixed bin (35)); 

call f i le__manager_$termi nate_ci_ptr (oid, ci_num, ci__ptr, code); 

ARGUMENTS 

oid 

is the opening identifier of the DM file. (Input) 
ci_num 

is the number of the control interval that ci_ptr points to. (Input) 
ci_ptr 

is the control interval pointer to be terminated. (Input) 

code 

is a standard system status code. (Output) 
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Name: find bit 

This subroutine uses the EIS test character and translate (TCT) instruction to 
efficiently perform common bit string search operations. Entrypoints are provided to 
return the bit index of the first or last occurrence of an on bit OT'b) or off bit 
("0"b) in a bit string. 

This subroutine operates by dividing the bit string into three search regions: a group 
of 9-bit bytes aligned on a byte boundary; bits preceding these bytes; and bits 
following the bytes. Bits preceding or following the bytes are examined bit by bit, 
using a separate compare bit (CMPB) instruction for each bit. The bytes are examined 
as a single character string, using one TCT instruction to test all bytes until a byte 
containing an on or off bit is found. For bit strings longer than 36 bits, this 
subroutine is significantly faster than the code generated by the PL/ 1 index builtin 
function, which test all bits on a bit-by-bit basis.. 



Entry: find bit Sfirst on 

This entrypoint returns the index (bit position) of the first (leftmost) bit that is on 
OT'b) in a bit string. 

USAGE 

declare f i nd_bi t_$f i rst_on entry (bit(*)) returns (fixed bin (2*0) 
reducible; 

index = f i nd_bi t_$f i rst_on (b i t_str i ng) ; 

ARGUMENTS 

bit_string 

is the bit string to be examined. (Input) 
index 

is the index of the first "l"b bit within the bit string. If no "l"b bits are found, 
then 0 is returned. (Output) 



Entry: find__bit_$first__off 

This entrypoint returns the index (bit position) of the first (leftmost) bit that is off 
("0"b) in a bit string. 

USAGE 

declare f i nd_b i t_$f i rst_of f entry (bit (>'<)) returns (fixed bin(2M) 
reduc ible; 

index = f i nd_b i t_$ firs t_of f (b i t_str i ng) ; 
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ARGUMENTS 
bit_string 

is the bit string to be examined. (Input) 
index 

is the index of the first "0"b bit within the bit string. If no "0"b bits are found, 
then 0 is returned. ' (Output) 



Entry: find_bit_$last__on 

This entrypoint returns the index (bit position) of the last (rightmost) bit that is on 
OT'b) in a bit string. 

USAGE 

declare f i nd_bi t_$ 1 ast_on entry (bit(*)) returns (fixed bin (2k)) 
reducible; 

index ■ f i nd__bi t_$ 1 ast_on (bi t_str i ng) ; 

ARGUMENTS 

bit_string 

is the bit string to be examined. (Input) 
index 

is the index of the last "l"b bit within the bit string. If no 'T'b bits are found, 
then 0 is returned. (Output) 



Entry: find_bit_$last__off 

This entrypoint returns the index (bit position) of the last (rightmost) bit that is off 
0'0"b) in a bit string. 

USAGE 

declare f i nd__bi t_$last_of f entry (bit(*)) returns (fixed bin (24)) 
reducible; 

index = f ind_bi t_$iast__off (bi t_str ing) ; 

ARGUMENTS 

bit_string 

is the bit string to be examined. (Input) 
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index 

is the index of the last "0"b bit within the bit string. If no "0"b bits are found, 
then 0 is returned. (Output) 



Name: find char 

This subroutine uses the EIS test character and translate (TCT) instruction to perform 
the function of the PL/I search and verify builtin functions in a highly efficient 
manner. Search and verify operations can be performed from either the left or the 
right end of the string. 

The search function looks for the first occurrence of any of a set of characters (the 
search characters) within an input character string. The verify function checks that all 
characters within an input string are also characters in a verify string; it searches in 
the input string for the first occurrence of a character not in the verify string. 

NOTES 

The TCT instruction uses a test-and-translate table to control the searching. 
Entrypoints are provided to build a table that can be used for several search or verify 
operations, or to build tables as part of each search or verify operation. 

The PL/ 1 compiler generates efficient, in-line TCT or TCTR instructions when the 
second argument of the search or verify builtin function is a constant (so that the 
test-and-translate table can be constructed at compile time). When the second 
argument is a variable, however, PL/ 1 uses a less efficient operator call to perform 
the search or verify operation. This operator tests each character of the first string to 
see if it appears in the second string. The rationale for the PL/T operator is that for 
short first arguments it is more expensive to construct a test-and-translate table at 
run-time than to do the indexing. Programs that must search lengthy strings with a 
variable second argument can use find_char_ to avoid using the PL/I operator, thereby 
regaining the efficiency of the TCT instruction. 

The test-and-translate table is an aligned, fixed-length character string, 512 characters 
long to cover all possible Multics 9-bit byte values. It consists of "\000" characters 
and non-\000 characters. Searching (or verifying) using a test-and-translate table 
progresses as follows: 

1) Examine the first (or next) character of the input string. If i is the index of the 
character being examined, then: 
input_char = substr(string, i, 1) 
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2) For each input_char, examine its corresponding table_char: 

table_char = substr(table,rank(input_char)+l,l) 

3) If table_char = "\000", then the test fails and the search continues with step 1. 

4) If table_char A = "\000", then the test succeeds and the search stops. The current 
value of i is returned as the index value. For the find_char_$translate_first_in_table 
and $translate_last_in_table entrypoints, table_char is also returned. 

5) If the input string- is exhausted before the test succeeds, then a value of 0 is 
returned as the index argument For the find_char_$translate_first_in_table and 
$translate_last_in_table entrypoints, "\000" is returned as the table_char. 



Entry: find char $first_in_list 

This entry performs the PL/I search function, returning the character index of the 
first (leftmost) occurrence of one of the search_chars in the input string. It constructs 
the test-and-translate table used by the TCT instruction from search_chars string 
provided by the caller. 

USAGE 

declare f i nd_char_$f i rst_i n_l i st entry (char (*) , char (*) ) 
returns (fixed b i n (2 1) ) reducible; 

index = f i nd_char_$f i rst_i n_l i st (string, search_chars) ; 

ARGUMENTS 

string 

is the character string to be searched. (Input) 
search_chars 

are characters to be found in the string. (Input) 
index 

is the result of the search. It is the PL/I string index (character position) of the 
first occurrence of one of the search_chars in the input string. 0 is returned if 
none of the search_chars appear in the input string. (Output) 
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Entry: find__char__$last_in__list 

This entry returns the character index (character position relative to the beginning of 
the string) of the last (rightmost) occurrence of one of the search_chars in the input 
string. It performs the PL/ 1 function: 

index = 1 ength (str i ng) - search (reverse (str i ng) , chars) + 1 

[when char searched for is found in string] 
index = 0 [when char searched for is not found.] 

It constructs the test-and-translate table used by the TCT instruction from search_chars 
string provided by the caller. 

USAGE 

declare f i nd_char_$ 1 ast_i n_l i st entry (char (*) , char(*)) 
returns (fixed b i n (2 1) ) reducible; 

index = f i nd_char_$ 1 ast_i n_l i st (string, search__chars) ; 

ARGUMENTS 
string 

is the character string to be searched. (Input) 
search_chars 

are characters to be found in the string. (Input) 
index 

is the result of the search. It is the PL/ 1 string index (character position) of the 
last (rightmost) occurrence of one of the searcb_ehar$ in the input string. 0 is 
returned if none of the search_chars appear in the input string. (Output) 



Entry: find__char__$first_ not in list 

This entry performs the PL/ 1 verify function, returning the character index of the 
first (leftmost) occurrence in the input string of a character which is not one of the 
verify_chars. It constructs the test-and-translate table from the verify_chars provided 
by the caller. 

USAGE 

declare f i nd_char_$f i rst_/iot__i n_l i st entry (char (>'<) ♦ char(*))- 
returns (fixed bin(21)) reducible; 

index = f i nd_char_$f i rst_not_i n_l i st (string, ver i f y_char s) ; 
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ARGUMENTS 
string 

is the character string to be searched. (Input) 
verify_chars 

are characters which are skipped over when searching the string. (Input) 
index 

is the result of the verify. It is the PL /I string index (character position) of the 
first (leftmost) occurrence of a character in the input string which is not one of 
the verify_chars. 0 is returned if the entire input string contains only the 
characters in verify_chars. (Output) 



Entry: find__char $last__not in list 

This entry returns the index (character position relative to the beginning of the string) 
of the last (rightmost) occurrence of a character in the input string which is not one 
of the verify_chars. It performs the PL/I function: 

index = 1 ength (str i ng) - verify (reverse (str i ng) , chars) + 1; 

[when character not in chars is found in string] 
index = 0; [when character not in chars is not found in string.] 

It constructs the test-and-translate table from the verify_chars provided by the caller. 
USAGE 

declare f i nd_char_$ 1 ast_not_i n_li st entry (char (*) , char(*)) 
returns (fixed b i n (2 1 ) ) reducible; 

index = f i nd_char__$ 1 ast_not__i n__l i st (string, ver i f y__chars) ; 

ARGUMENTS 

string 

is the character string to be searched. (Input) 
verify_chars 

are characters to be skipped over when searching the string. (Input) 
index 

is the result of the verify. It is the PL/ 1 string index (character position) of the 
last (rightmost) occurrence of a character in the input string which is not one of 
the verify_chars. 0 is returned if the entire input string contains only the 
characters in verify_chars. (Output) 
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Entry: find char Sfirst in table 

This entry point searches an input string from the left, using a user-defined 
test-and-translate table. Either a search or a verify operation can be performed, 
depending upon the contents of the table. find_char_$make_table_from_chars_in_list 
can be used to construct a search_table from a set of search_chars; 
find_char_$make_table_from_chars_not_in_list can be used to construct a verify_table 
from a set of verify_chars; or the user can create a table containing his own values. 
As described in the Notes, searching continues until an input string character 
corresponds to a nonzero element of the table. The character index of the input 
string character is returned. 

USAGE 

declare f i nd_char_$f i rst_i n_tabl e entry (char (*) , char (512) aligned) 
returns (fixed b i n (2 1 ) ) reducible; 

index = f i nd_char_$f i rst_i n_tabl e (string, table); 

ARGUMENTS 

string 

is the character string to be searched. (Input) 
table 

is the test-and-translate table. (Input) 
index 

is the result of the search. It is a PL/ 1 string index (character position) of the 
first (leftmost) input character corresponding to a nonzero table element. 0 is 

returned if no input characters correspond to a nonzero table element (Output) 



Entry: find char Slast in table 

This entry point searches an input string from the right, using a user-defined 
test-and-translate table. Either a search or a verify operation can be performed, 
depending upon the contents of the table. find_char_$make_table_from_chars_in_list 
can be used to construct a search_table from a set of search_chars; 
find_char_$make_table_from_chars_not_in_list can be used to construct a verify_table 
from a set of verify_chars; or the user can create a table containing his own values. 
As described in the Notes, searching continues until an input string character 
corresponds to a nonzero element of the table. The character index of the input 
string character is returned. 
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USAGE 

declare f i nd_char_$ 1 ast_i n_tabl e entry (char (*) , char(512) aligned) 
returns (fixed b i n (2 1 ) ) reducible; 

index = f i nd_char_$ 1 ast_i n_tabl e (string, table); 

ARGUMENTS 

string 

is the character string to be searched. (Input) 
table 

is the test-and-translate table. (Input) 

index 

is the result of the search. It is a PL/ 1 string index (character position) of the 
last (rightmost) input character corresponding to a nonzero table element 0 is 
returned if no input characters correspond to a nonzero table element (Output) 



Entry: find char $translate first_in__table 

This entry point searches an input string from the left, using a user-defined 
test-and-translate table. Either a search or a verify operation can be performed, 
depending upon the contents of the table. As described in the Notes, searching 
continues until an input string character corresponds to a nonzero element of the 
table. The character index of the input string character is returned, along with the 
nonzero table element 

USAGE 

declare f i nd_char__$ trans 1 ate_f i rst_i n_tabl e entry (char (*) , 
char (512) aligned, fixed bin(21)) returns (char(l)); 

table_element = f i nd__char_$ trans 1 ate__f i rst_i n_tabl e (string, table, 
i ndex) ; 

ARGUMENTS 

string 

is the character string to be searched. (Input) 

table 

is the test-and-translate table. (Input) 
index 

is the result of the search. It is a PL/ 1 string index (character position) of the 
first (leftmost) input character corresponding to a nonzero table element 0 is 
returned if no input characters correspond to a nonzero table element (Output) 
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table_element 

is the character from the test-and-translate table which corresponds to the input 
string character selected by index. "\000" is returned when index=0. (Output) 



Entry: find char $translate_Jast in table 

This entry point searches an input string from the right, using a user-defined 
test-and-translate table. Either a search or a verify operation can be performed, 
depending upon the contents of the table. As described in the Notes, searching 
continues until an input string character corresponds to a nonzero element of the 
table. The character index of the input string character is returned, along with the 
nonzero table element 

USAGE 

declare f i nd_char_$trans 1 ate_l ast_i n_table entry (char (*) , 
char (512) aligned, fixed bin(21)) returns (char(l)); 

table_element = f i nd_char_$ trans 1 ate_l ast_i n_tabl e (string, table, 
i ndex) ; 

ARGUMENTS 

string 

is the character string to be searched. (Input) 
table 

is the test-and-translate table. (Input) 
index 

is the result of the search, it is a FL/i string index (character position) of the 
last (rightmost) input character corresponding to a nonzero table element. 0 is 
returned if no input characters correspond to a nonzero table element. (Output) 

table_element 

is the character from the test-and-translate table which corresponds to the input 
string character selected by index. "\000" is returned when index=0. (Output) 



Entry: find char $make_table of chars in list 

This entry constructs a test-and-translate table for use with the find_char_$first_in_table 
and find_char_$last_in_table entrypoints. Table entries corresponding to characters of 
search_chars are marked with \777 in the search table. Other table entries are filled 
with \000. 
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USAGE 

declare f ind_char_$make_table__of_chars_in_l ist entry (char (*) ., 
char (512) al i gned) ; 

call f ind_char_$make_table_of_chars_in_l ist (search_chars, 
search_tabl e) ; 

ARGUMENTS 

search_chars 

is a string of characters whose corresponding entries are to be marked in the 
resulting translate table. (Input) 

search_table 

is the test-and-translate table. (Output) 



Entry: find__char $make table__of__chars not in list 

This entry constructs a test-and-translate table for use with the find_char_$first_in_table 
and find_char_$last_in_table entrypoints. Table entries corresponding to characters of 
verify = chars remain unmarked (\000 elements) in the table. Other table elements are 
filled with \777. 

USAGE 

declare f i nd_char_$make_tabl e__of _chars_not_i n_l i st entry (char (*) , 
char (512) al i gned) ; 

call f i nd_char_$make_tabl e_of_chars__not__i n_l i st (ver i f y_chars, 
ver i f y_tabl e) ; 

ARGUMENTS 

verify_chars 

is a string of characters whose corresponding entries are to remain unmarked in 
the resulting translate table. (Input) 

verify_table 

is the test-and-translate table. (Output) 
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Entry: find_char Snot ascii table 

This entry point is an external variable containing a predefined test-and-translate table 
which can be used to detect any non-ASCII characters in a character string. 
Non-ASCII characters are those in which one or both of the 2 leftmost bits of the 
9-bit character byte are "l"b (i.e., character > M \177"). The first 128 values in the 
table are "\000". The next 384 table characters are set to their character offset within 
the table. This means that: 

substr (table, n+1 , 1) = "\000", for n: 000 <* n <= 127 
substr (table, n+1,1) = "\n", for n: 128 <= n <= 5 1 1 



USAGE 

declare f i nd_char_$not_asc i i_tab 1 e char (512) al igned external static; 



Name: find_condition frame 

This subroutine returns a pointer to the most recent condition frame, or 
the most recent one before a specified frame. 

USAGE 

del f ind_cond it ion__frame_ entry (ptr) returns (ptr) ; 
stack__ptr ■ f i nd_cond i t i on_f rame_ (startjptr) ; 
ARGUMENTS 
start_ptr 

is a pointer to a stack frame. The most recent condition frame before this stack 
frame is returned. The start_ptr argument can be obtained by another call to 
find_condition_frame_. If start_ptr is null, the most recent condition frame is 
returned. (Input) 

stack_ptr 

is a pointer to the desired condition frame. (Output) 
NOTES 

The condition history can be traced by repeated calls to find_condition_frame_, 
starting with a null start_ptr argument and repeatedly passing the output stack_ptr as 
input. 
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Name: find condition info 

This subroutine, given a pointer to a stack frame being used when a signal occurred, 
returns information relevant to that condition. 



declare f i nd_cond i t ion_i nf o_ entry (ptr, ptr, fixed bin (35)) J 
call f ind_condi tion_info_ (stack_ptr, condi tion_Jnfo_ptr , code); 
ARGUMENTS 
stack_ptr 

is a pointer to a stack frame being used when a condition occurred. It is 
normally the result of a call to find_condition_frame_; if null, the most recent 
condition frame is used. (Input) 

condition_inf o_ptr 

is a pointer to the structure (see "Notes" below) in which information is returned. 



code 

is the standard status code. It is nonzero when the stack_ptr argument does not 

point to a condition frame or, if the stack_ptr argument is null, when no 
condition frame can be found. (Output) 



The structure that condition_info_ptr points to is declared in the include file 
condition_info.incl.pll. It is declared as: 



USAGE 



(Input) 



NOTES 



del 



condi tion_info 

2 mc_ptr 

2 version 

2 condi tion_name 

2 info__ptr 

2 wc_ptr 

2 loc_ptr 

2 flags 



3 padl 

2 pad 2 

2 -user_l oc_ptr 
2 pad 3 



3 crawlout 



aligned based (condi tion_i nfo_ptr) , 
ptr, 

fixed bin, 

char (32) varying, 

ptr, 

ptr, 

ptr, 

unal i gned, 
bit(l) , 

bit (35) , 
bit (36) , 
ptr, 

W bit (36); 
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STRUCTURE ELEMENTS 
mc_ptr 

if not null, points to the machine conditions. Machine conditions are described in 
the Programmer's Reference Manual. 

version 

is the version number of this structure. It should be set to condition_info_version_l. 
This variable is declared in condition_info.incl.pll. 

condition_name 

is the condition name. 

info_ptr 

points to the info structure if there is one; otherwise, it is null. The info 

structures for various system conditions are described in the Programmer's 

Reference Manual. 

wc_ptr 

is a pointer to machine conditions describing a fault that caused control to leave 
the current ring. This occurs when the condition described by this structure was 
signalled from a lower ring and, before the condition occurred, the current ring 
was left because of a fault Otherwise, it is null. 

loc_ptr 

is a pointer to the location where the condition occurred. If crawlout is "l"b, 
this points to the last location in the current ring before the condition occurred. 

crawlout 

indicates whether the condition occurred in a lower level ring in which it could 
not be adequately handled. 
"0"b no 
"l"b yes 

padl 

is currently unused and should be set to "0"b. 

pad2 

is currently unused and should be set to "0"b. 
user_loc_ptr 

is a pointer to the most recent nonsupport location before the condition occurred. 
If the condition occurred in a support procedure (e.g., a PL/I support routine), it 
is possible to locate the user call that preceded the condition. 

pad3 

is currently unused and should be set to "0"b. 
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Name: find include file 

The primary entry point of the f ind_include_f ile_ subroutine searches for an include 
file on behalf of a translator. If the include file is found, additional information 
about the segment found is returned in the parameters. The "translator" search list is 
used to locate the include file. 



Entry: find include file {initiate count 

This entry point is the interface presented to translators. A translator calls this entry 
point to invoke a search for a single include file segment using the "translator" search 
list. For more information about search lists, see the search facility commands, and in 
particular the add_search_paths command in the Commands manual. 

USAGE 

declare f i nd_i nc 1 ude_f i 1 e_$ i n i t i ate_count entry (char (*) , ptr, char (*) , 
fixed bin (24), ptr, fixed bin (35)); 

call f i nd_i nclude_f i le_$ i ni t i ate_count (translator, ref erenc i ng_ptr , 
filename, bit_count, seg_ptr, code); 

ARGUMENTS 

translator 

is the name of the translator that is calling this procedure (e.g„ pll, aim). (Input) 
referencing_ptr 

is a pointer into the segment (normally a pointer to the source line) that caused 
the invocation of this instance of this procedure. (Input) 

file_name 

is the complete entryname of the include file this procedure is to locate (e.g., 
xxx.incl.pll). (Input) 

bit_count 

is the bit count as obtained from the storage system of the found include file. 
(Output). If an include file is not found, this parameter is set to 0. 

seg_ptr 

is a pointer to the first character of the include file, if found; if not found, this 
parameter is set to the null pointer value. (Output) 
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code 

is a standard status code. (Output). The code can be: 
0 

the requested file was found normally. All output parameters have been set 

normally. 
error_table_$zero_length_seg 

the requested file was found, but the bit count was zero. All output 

parameters have been set normally. 
error_table_$noentry 

the requested file was not found in any of the search directories, 
other storage system error codes 

the requested file was not found because of some error. 

NOTES 

If this procedure finds an include file by a link, the seg_ptr parameter correctly 
designates the actual location of the include file. It is possible, however, that the 
name of the actual include file is not the same as the file_name argument passed to 
this procedure. It is the responsibility of the translator to determine if the file_name 
passed to this procedure is also on the include file actually found. It is also the 

. "u: i j *---t — c 4-1 — —-11 + v. „ t — ~ <p + ~— — — ~ — ~ *■ am 

include file when processing is complete. 



Name: find partition 

The find_partition_ subroutine is used to ascertain information about a disk partition 
located on some mounted storage system disk. It reads the label and locates the 
partition, returning information about its size and location, as well as returning the 
PVID of the volume, for use in a later call to one of the hardcore entries for 
partition reading and writing. Use of this subroutine requires access to phcs_. 

USAGE 

del f i nd_parti tion_ entry (char (*) , char (*) , bit (36) aligned, 
fixed bin (35), fixed bin (35), fixed bin (35)); 

call f ind_parti tion_ (pvname, par t i t ion_name, pvid, f i rst_reeord, 
parti tion_size, code); 

ARGUMENTS 

pvname 

is the name of the physical volume on which the partition is located. (Input). 
The volume must be a presently mounted storage system disk volume. 
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partition_name 

is the name of the disk partition to be located. (Input). It must be four 
characters long or shorter. 

pvid 

is the physical volume ID of the volume the partition is located on. (Output). 
This is returned as a convenience, for use in a later call to one of the hardcore 
entries for partition' I/O. 

first_record 

is the number (zero origin, from the beginning of the volume) of the first record 
in the partition. (Output) 

partition_size 

is the number of words in the partition. (Output) 

code 

is a nonstandard status code. (Output). It can be one of the following: 
0 

indicates that the partition exists and that the returned parameters are all 
correct 

error_table_$pvid_not_f ound 

indicates that the specified physical volume is not presently mounted. 
error_table_$entry_not_f ound 

indicates that the specified partition could not be found, 
an integer between 1 and 10 

indicates that a physical disk error occurred while trying to read the label. 

Error messages for physical disk errors are declared in the include file 

fsdisk_errors.incl.pll, in the array fsdisk_error_message. 



Name: find source file 

Finds a file given a pathname and an optional suffix. Translators use this to find 
source programs. 

USAGE 

declare f i nd_source_f i le_ entry (char (*) , char (*) , char (>*«) , ptr, 
f i xed bin (24) , f i xed bin (35) ) ; 

call f i nd_source_f i 1 e_ (pathname, suffix, entryname, source_ptr, 
bi t__count, code) ; 

ARGUMENTS 

pathname 

is the pathname of the source segment. (Input) 



11/86 



2-289 



AG93-05A 



find_source_file_ 



find_source_file_ 



suffix 

is the suffix to be added to the pathname (if one does not already exist). (Input) 
entryname 

is the entryname of the source segment. (Output) 
source_ptr 

is a pointer to the base of the source segment. It is null if the source could not 
be found. (Output) 

bit_count 

is the bit count of the source segment. (Output) 

code 

is a standard system status code. (Output) 



Entry: find source file Ssearch path 

Finds a file given a pathname and an optional suffix. Translators use this to find 
source programs. A search list is used to locate the source file (e.g. ; the probe search 
list). 

USAGE 

del f i nd_source_f i 1 e_$search_path entry (char (*) , char (*) , char (*) , 
char (*) , ptr, fixed bin (2*0, fixed bin (35)); 

call f i nd_source_f i 1 e_$search_path (pathname, suffix, search_l i st_name, 
entry__name, source_ptr, bit_count, code); 

ARGUMENTS 

pathname 

is the pathname of the source segment. (Input) 
suffix 

is the suffix to be added to the pathname (if one does not already exit). (Input) 
search_list_name 

is the search list to use to locate the source file specified by the pathname and 
suffix input arguments. (See "Notes" below.) (Input) 

entryname 

is the entry name of the source segment. (Output) 
source_ptr 

is the pointer to the base of the source segment. It is null if the source could 

* i__ r i //"v..- *\ 

nut uc lumiu. vwuipui; 
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bit_count 

is the bitcount of the source segment (Output) 

code 

is a standard system status code. (Output) 
NOTES 

If the $search_path entry is used, the "referencing_dir" keyword is interpreted to be 
the directory portion of the pathname input argument 



Name: format document 

The format_document_ subroutine is used to fill and adjust text. The subroutine 
arguments control the formatting, some of which can be overridden by optional 
control lines in the text. See the "Notes" section below for a discussion of those 
control lines. 

The format_document_ entry point uses directory names and entrynames. The 
entrynames can reference segments, links, or multisegment files. 

USAGE 

declare forma t_document_ entry (char (*) , char (*) , char (*) , char (*) , ptr, 
fixed bin (35)) ; 

call f ormat_document_ (d i r_name_i n, entry__name__i n, d i r_name_out, 
entry_name_out , options_ptr, code); 

ARGUMENTS 

dir_name_in 

is the pathname of the containing directory of the input (Input) 
entry_name_in 

is the entryname of the input segment, link or multisegment file. (Input) 
dir_name_out 

is the pathname of the containing directory of the output (Input) 
entry_name_out 

is the entryname of the output segment, link or multisegment file. (Input) If the 
entry does not exist, it will be created. 
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options_ptr 

is a pointer to the structure in which options are specified. (Input) See "Notes" 
below. 

code 

is a standard status code. (Output) It may be one of the following: 
error_table_$f atal_error 

if the input file cannot be processed. 
error_table_$recoverable_error 

if an error occurs but processing is completed. 



Entry: format__document__$string 

This entry point uses char (*) variables as input and output. 
USAGE 

declare f ormat_document__$str i ng entry (char (*) , char (*) , fixed bin (21), 
ptr, fixed bin (35)) ; 

call f ormat__document_$str i ng (instring, outstring, outlen, options_ptr, 
code) ; 

ARGUMENTS 

instring 

is the input string. (Input) 

outstring 

is the output string. (Input) 

outlen 

is the length in bytes of the output string. (Output) 
options_ptr 

is a pointer to the structure in which options are specified. (Input) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$smallarg 

if the size of the output exceeds that of the output string. 
error_table_$f ataLerror 

if the input file cannot be processed. 
error_table_$recoverable_error 

if an error occurs but processing is completed. 
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Entry: format document $s witch 

This entry point uses a directory name and entryname for input and writes its output 
to an I/O switch. The entryname can reference a segment, link or multisegment file. 

USAGE 

declare format document $switch entry (char (*) , char (*) , ptr, ptr, 
fixed bin (35)) ; 

call f ormat_document_$swi tch (di r_name_i n, entry__name_J n, iocbptr, 
options_ptr, code); 

ARGUMENTS 

dir_name_in 

is the pathname of the containing directory of the input. (Input) 
entry_name_in 

is the entryname of the input segment, link or multisegment file. (Input) 
iocbptr 

is a pointer to the control block for the output I/O switch. (Input) 
options_ptr 

is a pointer to the structure in which options are specified. (Input) See "Notes" 
below. 

code 

is a standard status code. (Output) It can one of the following: 
error_table_$f atal_error 

if the input file cannot be processed. 
error_table_$recoverable_error 

if an error occurs but processing is completed. 
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NOTES 

The argument options_ptr points to the following structure (defined in include file 
format_document_options.incl.pll): 

del 1 f ormat_document_opt ions 
2 version_number 
2 indentation 
2 line_length 
2 switches, 

3 pgno_sw 

3 adj_sw 

3 gal 1 ey_sw 

3 error_sw 

3 1 i teral_sw 

3 f i i e_sw 

3 dont_compress_sw 
3 break_word_sw 
3 max__l i ne_length_sw 
3 dont_break_i ndentsd 

3 sub_err_sw 
3 dont__f i 1 l_sw 
3 hyphenat ion__sw 
3 mbz 
2 syl lable_size 

STRUCTURE ELEMENTS 

version_number 

is the version number of this structure. (Input) It must have the value 2. 
indentation 

indentation value, causing indentation from the left margin. (Input) This space is 
in addition to any indentation established by the usage of the indent control in 
the text. 

linejength 

is the initial line length value. (Input) It is the equivalent of the ".pdw" control 
in the text, and can be overridden in the text 

pgno_sw 
(Input) 

"l"b enables page numbering. If galley_sw is off, then each page is to end with 

a centered page number. 
"0"b indicates that no page numbering is requested. 



aligned based (forma t_document_opt ions_ptr) , 
fixed bin, 
fixed bin, 
fixed bin, 
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adj_sw 
(Input) 

"l"b causes adjust mode to be on initially. This is the equivalent of a ".alb" in 

the text. It can be overridden in the text 
"0"b causes adjust mode to be off initially. This is the equivalent of a ".all" in 

the text It is only meaningful if dont_fill_sw = "0"b. 

galley_sw 
(Input) 

"l"b suppresses vertical margins and page breaks. 
"0"b enables vertical margins and page breaks. 

error_sw 
(Input) 

"l"b causes diagnostic error messages to be written to error_output. 
"0"b suppresses diagnostic error messages. 

literal_sw 
(Input) 

"l"b causes all input to be treated as text. 

"0"b enables format_document_ controls. A line that begins with a period is 
treated as a control line. 

file_sw 

(Output) 

"l"b indicates that a non-zero storage system status code refers to the output file. 
"0"b indicates that a non-zero storage system status code refers to the input file. 

dont_compress_sw 
(Input) 

"l"b causes no compression of adjacent spaces and tab characters, nor enforcement 
of the convention of ending a sentence with 2 spaces. 

"0"b causes adjacent spaces and tab characters that do not begin a line to be 
converted to a single space, and enforces the convention that a sentence 
ends with 2 spaces. A sentence is any string that terminates with one of 
the following character sequences: ". "; "? "; " "; ": "; ".) "; "?) "; or 
" ) ". This switch may be overridden by dont_break_indented_lines for 
certain input lines. 

break_word_sw 
(Input) 

"l"b causes the line to be broken in the middle of a word if the line exceeds 
the line length and there are no spaces or tab characters available at 
which to do so. 

"0"b causes an overlength line to be returned and error_table_$recoverable_error 
to be returned if the line exceeds the linelength and there are no spaces 
or tab characters at which to break it. 
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max_line_length_sw 
(Input) 

"l"b causes the line to be re-adjusted to the linejength given in this structure 
and error_table_$recoverable_error to be returned if controls in the text 
cause the calculated line length to be greater than the line_length given in 
this structure. 

"0"b allows the controls in the text to adjust the calculated line length to a value 
greater than the linejength given in this structure. 

dont_break_indented_lines_sw 
(Input) 

"l"b indicates that if an input line exceeds the specified line length and begins 
with a blank or horizontal tab, it is not to be broken if a) it is the last 
line of input, b) it is followed a line that begins with a blank or 
horizontal tab, or c) it is followed by a blank line. In addition, such lines 
will not have space compression or sentence formatting performed on 
them, no matter what value dont_compress_sw has. 

"0"b indicates that overlength lines are broken regardless of indentation, and that 
dont_compress will always control space compression and sentence formatting. 

sub err sw 
(Input) 

"l"b indicates that diagnostic errors are to be communicated via calls to sub_err_. 

The info structure used to communicate information about the error is 

f ormat_document_error.incl.pll. 
"0"b indicates that no calls to sub_err_ are to be made. 

dont_fill_sw 
(Input) 

"l"b causes fill mode to be off initially. This is the equivalent of a ".fif" in the 

text. It can be overridden in the text. 
"0"b causes fill mode to be on initially. This is the equivalent of a ".fin" in the 

text. 

hyphenation_sw 
(Input) 

"l"b causes hyphenation mode to be on initially. Hyphenation can be turned on 
in the text via the "hyn" control and off via the ".hyf" control. The ".hy" 
control returns hyphenation mode to the initial value, i.e. the state of this 
switch. 

"0"b causes hyphenation mode to be off initially. 

mbz 

must be zero. 
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syllable_size 
(Input) 

indicates the smallest number of characters to be contained in a syllable that is to 
be separated from the rest of a word by hyphenation. This value can be adjusted 
in the text via the ".hyn" control. The ".hy" control returns the syllable size to 
the value of this argument. 

CONTROL LINES 

The following is a discussion of each of the control lines, 
.alb 

align the text at both the left and right margins according to the current value of 
the left indentation and undentation. Text is padded by insertion of uniformly 
distributed white space. The fill mode must be on for this mode to operate. If 
the fill mode is off, this control is mapped into the align-left (.all) control. This 
is the default alignment mode. 

.all 

align the text on the left margin according to the current values of left 
indentation and undentation leaving the right margin ragged. 

.brf 

finish the current output line by formatting any pending texts as a short line, 
.brf finish the current page, formatting any pending texts as a short line, 
.fif 

set the fill mode off. See the discussion of .fin for details. 

.fin 

set the fill mode on. In fill mode, text words are moved from line to line in 
such a way that the last word does not extend past the right margin. The default 
for this mode is on. 

set hyphenation mode and syllable size to the defaults: 
f ormat_document_options.hyphenation_sw f ormat_document_options.syllable_size. 

.hyf 

set hyphenation mode off. See the discussion of .hyn for details. 

.hyn {N} 

set hyphenation mode on and set the syllable size according to the given 
parameter, the parameter is given as an unsigned integer and specifies the number 
of characters in the smallest allowed hyphenated syllable. If the parameter is not 
given, then the default syllable size is used. The default syllable size is the value 
given in format_document_options.syllable_size. 
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.in, .inl {+/-N} 

if N is given without the optional sign, plus (+) or minus (-), then set the left 
indentation point to N columns to the right of the left margin. If N is given 
with the optional sign, then change the current left indentation point by N 
columns. Positive values for N cause movement to the right The default value 
for N is 0. Any value that results in a zero or negative effective line length will 
produce an error diagnostic message. The left indentation point is never set to 
the left of the left margin. The left margin is determined by the -indent control 
argument. 

.pdl W-N} 

if N is given without the optional sign, (+ or -), then set the page length to N 
lines. If N is given with the optional sign, then change the current page length 
by N. If the resulting page length is zero or negative, an error diagnostic 
message is produced. The default value for N is 66. 

.pdw {+/-N} 

if N is given without the optional sign, then set the page width to N columns. If 

N is given with the optional sign, then change the current page width by N. If 

the resulting page width is zero or negative, an error diagnostic message is 

] 1 nru - i c vt ;„ cc 

pjuuui/ou. liic uuaun vaiuc iui v\ va uj. 

.spf {N} 

finish the current output line and then add N blank lines. If N is not given, 
then add 1 blank line. 

.un, .unl {+/-N} 

adjust the indentation point for only the next output line. If N is unsigned or 
has the + sign the indentation point is moved n columns to the left. If N has 
the - sign, the indentation point is moved n columns to the right The default 

value for N is the value of the indentation value 



SPECIALIZED ERROR HANDLING 



If format_document_options.sub_err_sw is set and errors occur in formatting, the 
sub_err_ subroutine will be called to signal them rather than aborting the program. 
The caller of format_document_ can set up a handler for the sub_error_ condition 
and use the information in the format_document_error structure to make decisions 
about how to proceed. See the sub_err_ subroutine for an example of how to 
establish a handler for the sub_error condition. 

del 1 f ormat_document_error aligned based (f ormat_document_error_ptr) , 
2 version_number fixed bin, 

2 error_code - fixed bin (35) » 

2 1ine_number fixed bin, 

2 text_line char (128) varying; 

del f ornrat__document_error_ptr ptr; 
del f ormat_document__error__ver s i on_l fixed bin int 
static options (constant) init (1); 
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STRUCTURE ELEMENTS 
version_number 

is a number representing the version of the format_document_error structure being 
used. The structure above is version 1. 

error_code 

is a standard error- code from the fdoc_et_ error table describing the problem 
encountered. It can be used in a call to com_err_ or convert_status_code_ to 
announce the error. 

line_number 

is the line number on which the error appears in the input 

text_line 

is the offending line (or first 128 chars). 



The following values can occur in the error_code element of the format_document_error 
structure: 

LIST OF ERROR CODES 



fdoc_et_$indent_too_far_left, fdoc_et_$indtflft 

Attempted to indent past left margin; resets to left margin. 

f doc_et_$indent_too_f ar_right, f doc_et_$indtf rgt 

Attempted to indent past right margin; resets to right margin. 

f doc_et_$line_length_too_small, f doc_et_$himtsml 
Effective line length is less than 1. 

f doc_et_$line_too_long, f doc_et_$lntoolng 

Located a string of more than 256 characters without blank or newline. 

f doc_et_$no_parameter_allowed, f doc_et_$noparalw 
This control supports no parameters. 

f doc_et_$nonnumeric_parameter, f doc_et_$nonumpar 
A non-numeric parameter. 

f doc_et_$page_iength_It_13, f doc_et_$pgmiti3 

Given page length is too small; resets to the current minimum of 13. 

fdoc_et_$page_length_lt_14, fdoc_et_$pglnltl4 

Given page length is too small; resets to the current minimum of 14. 

f doc_et_$page_width_exceeds_max, f doc_et_$pgwdxmax 

The computed page width is too large; resets to the specified maximum. 



11/86 



2-290.9 



AG93-05A 



f ormat_document_ 



fs_util_ 



f doc_et_$text_too_long_f or_line, f doc_et_$txttulng 
Text is too long for output line. 

fdoc_et_$undent_too_far_left, fdoc_et_$undtflft 

Attempted to undent past left margin; resets to left margin. 

f doc_et_$undent_too_f ar_right, f doc_et_$undtf rgt 

Attempted to undent past right margin; resets to right margin. 

f doc_et_$unsupported_control, f doc_et_$unsupctl 
The given control is unsupported. 



Name: fs util 

The fs_util_ subroutine provides for uniform handling of file system entries. 
Supported operations are validate, copy, delete, chname, get_switch, set_switch, 
get_max_length, set_max__length, set_bit_count, and ACL manipulation. When invoked, 
the subroutine checks to see if the entry name provided is that of an extended entry 
and if it is, calls the corresponding entry point of the appropriate suffix_XXX_ 
subroutine. If the name is not that of an extended entry, then fs_util_ calls the 
appropriate standard entry entry point handler for the entry. 



Entry: fs util $add acl entries 

This entry point is used to add to the Access Control List of an entry. If an access 
name already appears on the ACL of the entry, its mode is changed to the one 
specified by the call. 

USAGE 

declare f s_ut i l__$add_ac l_entr i es entry (char (*) , char (*) , ptr, fixed 
bin (35)); 

call fs_uti l__$add_ac gentries (di rename, entryname, acl_ptr, code); 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 
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acl_ptr 

is a pointer to the general_acl structure. (Input) 

code 

is a standard system status code. (Output) 
NOTES 



The general_acl structure and the named constant GENERAL_ACL_VERSION_l are 
defined in the include file acl_structures.incl.pll. 

The general_acl structure is defined as follows: 

1 general_acl aligned based (acl_ptr) , 

2 version char (8) aligned, 

2 count fixed bin, 

2 entries (acl_count refer (general_acl .count) ) 

aligned like general_acl_entry ; 



1 general_ac l_entry 
2 access_name 
2 mode 

2 status code 



based , 

character (32) unaligned, 
bit (36) al i gned, 
fixed bin (35) ; 



STRUCTURE ELEMENTS 



version 

is the current version of this structure and has the value of the named constant 
GENERAL_ACL_VERSION_l. 

count 

is the size of the entries array in general_acl. 
access_name 

is the name of a user in the form of Person_id. Projected. instance_tag. 
mode 

is a bit string where each bit represents a possible access mode which, when true, 
indicates an allowed access for the file, access_mode_values.incl.pll defines named 
constants for the mode values of standard entries. Modes for extended entries are 
defined by the subsystem owning the extended entry type. Use the describe_entry_type 
command to display extended mode values. 

status_code 

is a standard system status code indicating success or the reason for failure to set 
the ACL entry. 
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Entry: fs util $add extended acl entries 

This entry point is used to add to the Extended Access Control List of a standard 
entry. 

USAGE 

declare fs uti l_$add_extended_acl_entr ies entry (char (*) , char (*) , ptr, 
f ixed bin (35)) ; 

call f s_ut i l_$add_extended_ac l_entr i es (dir_name, entryname, acl_ptr, 
code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

acl_ptr 

is a pointer to the structure general_extended_acl. (Input) 

code 

is a standard system status code. (Output) 
NOTES 

This interface is intended to be used only by extended entry type support routines, 
(also referenced as suffix_XXX_), in order to map an ACL mode provided to fs_util_ 
into a standard mode/extended mode pair to be placed on the underlying standard 
entry or entries which are being used to implement the extended entry type. 

The general_extended_acl structure and the named constant 
GENERAL_EXTENDED_ACL_VERSION_l are defined in the include file 
acl_structures. incl. pll. 
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The general_extended_acl structure is defined as follows: 

1 genera l_extended_ac 1 aligned based (acl_ptr) , 

2 version char (8) aligned, 

2 count fixed bin, 

2 entries (acl_count refer 

(genera l_extended_acl .count) ) 
aligned like genera l_extended_ac l_entry; 

1 genera 1 _extended_ac l_entry aligned based, 

2 access_name character (32) unaligned, 

2 mode bit (3&) aligned, 

2 extended_mode bit (36) aligned, 

2 status code fixed bin (35); 



STRUCTURE ELEMENTS 



version 

is the current version of this structure and has the value of the named constant 
GENERAL_EXTENDED_ACL_VERSION_l. 

count 

is the size of the entries array in general_extended_acl. 
access_name 

is the name of a user in the form of Person_id.Project_id.instance_tag. 
mode 

is a bit string where each bit represents a possible access mode which, when true, 
indicates an allowed access for the file. 

extended_mode 

is a bit string where each bit represents a possible extended access mode which, 
when true, indicates an allowed access for the file. 

status 

is a standard system status code indicating success or the reason for failure to set 
the extended ACL entry. 
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Entry: fs util Schname file 

This entry point is used to change the name of an entry. If only an old_name is 
given, the effect is to delete. If only a new_name is given, the effect is to add the 
name. If both are specified, the effect is to rename the entry. 

USAGE 

declare f s_ut i l_$chname_f i 1 e entry (char (*) , char (*) , char (*) , char (*) , 
fixed bin (35)) ; 

call f s_ut i l_$chname_f i 1 e (dir_name, entryname, old_name, new_name, 
code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

old_name 

is the name to be deleted from the entry. (Input) It can be a null character 

string ("") in which case no name is deleted. If old_name is null, the new_name 
must not be null. 

new_name 

is the new name to be added to the entry. (Input) It must not already exist in 
the directory on this or another entry. It can be a null string ("") in which case 
no name is added to the entry. It it is null, then old_name must not be the 
only name on the entry, 

code 

is a standard system status code. (Output) 



Entry: fs util__$copy 

This entry point is used to copy an entry. 
USAGE 

declare f s__ut i l__$copy entry (ptr, fixed bin (35)); 
call f s_ut i l_$copy (copy_opt i ons_ptr , code); 
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ARGUMENTS 



copy_options_ptr 

is a pointer to the copy_options structure. (Input) 

code 

is a standard system status code. (Output) 
NOTES 



The copy_options structure and the named constant COPY_OPTIONS_VERSION_l are 
defined in the include file copy_options.incl.pll. 

The copy_options structure is defined as follows: 



1 copy_options 

2 version 

2 cal 1 er_name 
2 source_dir 
2 source_name 
2 target_dir 
2 target_name 
2 flags, 

3 no_name_dup 

3 raw 

3 force 

3 delete 

3 target_err_swi tch 
3 mbz 
2 copy_i terns 



aligned based (copy_options_ptr) , 

char (8) , 

char (32) unal, 

char (168) unal, 

char (32) unal, 

char (1 68) unal , 

char (32) unal, 



bit (1) unal i gned, 

bit (1) unal i gned, 

bit (1) unal i gned, 

bit (1) unal i gned, 

bit ( 1 ) una 1 i gned , 

bit (31) unal i gned, 
1 i ke copy_f 1 ags ; 



STRUCTURE ELEMENTS 



version 

is the current version of this structure and has the value of the named constant 
C0PY_0PTI0NS_VERSI0N_1. 

caller_name 

is the name of the program calling fs_util_, required when querying the user 
about duplicate names. See no_name_dup below. 

source_dir 

is the absolute pathname of the directory containing the entry to be copied. 

source_name 

is the name of the entry to be copied. 
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target_dir 

is the absolute pathname of the directory into which a copy of the entry is to be 
placed. 

target_name 

is the name of the entry created to hold the copy of the original entry. 
no_name_dup 

is set to "0"b if the user is to be queried in case of a duplication of the 
target_name and "l"b if there is to be no query, in which case an error code 
will be returned. 

raw 

is set to "0"b if fs_util_ is to honor the extended type of the entry, and "l"b if 
it is to bypass this by calling hcs_. 

force 

is set to 'T'b if access to the target is to be forced, 
delete 

is set to 'T'b if the original is to be deleted after it is copied. 

target_err_switch 

is set if an error occurred referencing the target 

mbz 

is reserved for future use and must be set to zero. 
copy_items 

is structured like the copy_flags structure, which is defined in the include file 
copy_fiags.inci.pii. The structure is defined as follows: 



copy_f 1 ags 


a 1 i gned 


based, 


2 names 


bit ( 


1) 


una 1 i gned , 


2 acl 


bit ( 


1) 


una 1 i gned , 


2 r i ng_brackets 


bit ( 


0 


unal igned, 


2 max_length 


bit ( 


1) 


unal igned, 


2 copy_switch 


bit ( 


1) 


unal i gned, 


2 saf ety_swi ten 


bit ( 


n 


unal igned, 


2 dumper_swi tches 


bit ( 


0 


una 1 i gned, 


2 entry_bound 


bit ( 


i) 


unal igned, 


2 extend 


bit ( 


i) 


unal i gned, 


2 update 


bit ( 


i) 


unal igned, 


2 mbz 


bit ( 


26) 


unal i gned 
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When variables in the copy_flags structure have a value of "l"b, the designated 
attribute is copied to the new entry. Before the copy is performed, the 
copy_i terns members are ANDed with copy_flags members as defined by the 
suffix_info entry point Only those attributes specified by both structures are 
copied. In the case of extend, the contents of the original entry may be 
appended to the end of the target entry. In the case of update, the contents of 
the original entry may replace the contents of the target entry. 



Entry: fs util Sdelete acl entries 

This entry point deletes a member of an entry's Access Control List. 
USAGE 

declare f s_ut i 1_$del ete_ac l_entr i es entry (char («) , char (*) , ptr, fixed 
bin(35)); 

call f s_uti l_$delete_acl_entr i es (dir_name, entryname, acl_ptr, code); 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

acl_ptr 

is a pointer to the structure general_delete_acl. (Input) 

code 

is a standard system status code. (Output) 
NOTES 

The general_delete_acl structure and the named constant 
GENERAL_DELETE_ACL_VERSION_l are defined in the include file 
acl_struc tures. incl . pi 1 . 
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The general_delete_acl structure is defined as follows: 

1 genera l_delete_acl aligned based (acl_ptr) , 

2 version char (8) aligned, 

2 count fixed bin, 

2 entries (acl_count refer 

(general_de1ete_acl .count)) 
aligned like del ete__ac l_entry ; 

declare 1 general_delete_acl_entry aligned based, 

2 access_name character (32) unaligned, 

2 status code fixed bin (35) 5 



STRUCTURE ELEMENTS 



version 

is the current version of this structure and has the value of the named constant 
GENEFvAL_DELETE_ACL_VERSION_l. 

count 

is the size of the entries array in general_delete_acl. 
access_name 

is the name of a user in the form of Person_id.Project_id.instance_tag 
status_code 

is a standard system status code indicating success or the reason for failure to set 
the extended ACL entrv. 



Entry: fs util Sdelentry file 

This entry point deletes a file system entry. 
USAGE 

declare f s_ut i 1_$del entry_f i 1 e entry (char (*) , char (*) , fixed bin (35)); 
call f s_ut i l_$delentry_f i le (di rename, entryname, code) 
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ARGUMENTS 
dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

code 

is a standard system status code. (Output) 
Entry: fs util $get bit count 

This entry point returns the number of useful bits in an entry. 
USAGE 

declare f s_ut i l_$get_bi t_count entry (char (*) , char («) , fixed bin (41), 
fixed bin (35)) ; 

call f s_uti l_$get_bi t_count (dir_name, entryname, bit_count, code); 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

bit_count 

is the number of bits considered useful in the entry. (Output) 

code 

is a standard system status code. (Output) 
Entry: fs util__$get__max__length 

This entry point returns the maximum length setting for an entry. 
USAGE 

declare f s_ut i l_$get_max_l ength entry (char (*) , char (*) , fixed bin (35) » 
fixed bin (35)) ; 

call fs_ut i l_$get_max_1 ength (dir_name, entryname, max_length, code); 
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ARGUMENTS 
dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

max_length 

is the maximum length of the entry in words. (Output) 

code 

is a standard system status code. (Output) 



Entry: fs util $get ring brackets 

This entry point returns the ring brackets of an entry. 
USAGE 

declare f s_ut i l_$get_r i ng_brackets entry (char (*) , char (*) , (*) f i xed 
bin(3) , fixed bin (35)) ; 

call f s_ut i l_$get_r i ng_brackets (dir_name, entryname, r i ng_brackets, 
code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

ring_brackets 

are the ring numbers which define the upper bounds of the ring brackets which 
control the various modes of access to the entry. (Output) Ring brackets are 
discussed in "Intra Process Access Control" in the Multics Programmer's 
Reference Manual, Order No. AG91. 

code 

is a standard system status code. (Output) 
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Entry: fs__util $get switch 

This entry point returns the value of a storage system switch for an entry. 
USAGE 

declare f s_ut i l_$get_swi tch entry (char (*) , char (*) , char (*) , bit(l) 
aligned, fixed bin (35)); 

call f s_ut i l_$get_swi tch (dir_name, entryname, switch_name, value, 
code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

switch_name 

is the name of the switch whose value is sought. For example, it may be one of 
the following: "copy," "complete_volume_dump," "damaged," 

"incremental_volume_dump," "safety," "synchronized," or any additional switch 
supported by the appropriate extended entry type. (Input) 

value 

is the value of the requested switch. (Output) 

"l"b means the switch is on 
"0" means that it is off. 

code 

is a standard system status code. It should be set to error_table_$argerr if 
switch_name is invalid. (Output) 



Entry: fs util $get type 

This entry point returns the type of a specified entry. 
USAGE 

declare f s_ut i l_$get_type entry (char (*) , char (*) , char (*) , 
f ixed_bin(35)) ; 

call f s_ut i l_$get_type (dir_name, entryname, type, code); 
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ARGUMENTS 
dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

type 

is either the suffix if extended, or one of the name constants for standard entry 
types found in the include file suffix_info.incl.pll. (Output) 

code 

is a standard system status code. (Output) 



Entry: f s util $get user access modes 

This entry point returns a user's effective access mode and extended access mode for 
an entry. For a description of modes, see "Effective Access" in the Multics 
Programmer's Reference Manual, Order No. AG91. 

USAGE 

declare f s_ut i l_$get_user_access_modes entry (char (*) , char (*) , char (*) , 
fixed bin, bit(3&) aligned, bit(36) aligned, fixed bin (35)); 

call f s_ut i l_$get_user_access_modes (dir_name, entryname, user_name, 
ring, modes, exmodes, code); 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

user_name 

is the access name of the user in the form Person_id.Project_id.tag. (Input) This 
is limited to 32 characters. If null, the access name of the calling process is used. 

ring 

is the validation level that is to be used in computing effective access. (Input) It 
must be a value between 0 and 7 inclusive, or -1. If the ring value is -1, the 
default value of the validation level of the calling process is used. This default 
should be used in all cases except those in which a different ring's access is 
explicitly required. 
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are the standard ACL modes of an entry. (Output) 
xmodes 

are the extended ACL modes of an entry. (Output) 

code 

is a standard system status code. (Output) 
NOTES 

The include file access_modes_values.incl.pll defines named constants for the different 
values of modes. Extended access modes are defined by the subsystem owning the 
extended entry. 



Entry: fs util Slist acl 

This entry point lists the components of an entry's Access Control List 
USAGE 

declare fs util $list_acl entry (char (*) , char (*) , char (>"<) , ptr, ptr, 
fixed binl35)) ; 

call f s_uti 1_$1 i st_acl (dir_name, entryname, version, area_ptr, acl_ptr, 
fixed bin(35)) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

version 

is the version of the acl structure. (Input) 
area_ptr 

is a pointer to an area where fs_util_ can allocate the general_acl structure. If 
area_ptr is null, then the user wants access modes for certain ACL entries; these 
will be specified by the structure pointed to by acLptf. (Input) 
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acl_ptr 

is a pointer to the general_acl structure. (Input or Output) 

Input: if area_ptr is null, then acl_ptr points to a general_acl structure filled 
with access names and into which modes will be placed. 

Output: if area_ptr is non null, then acl_ptr will point to the start of a newly 
allocated general_acl structure. 

code 

is a standard system status code. (Output) 
NOTES 

If aci_ptr is used to obtain modes for specified access names (rather than for all 
access names on an entry), then each ACL entry in the general_acl structure either has 
status_code set to 0 and contains the entry's mode or has status_code set to 
error_table_$user_not_found and contains a mode of 0. 

The general.acl structure and the named constant GENERAL_ACL_VERSION_l are 
defined in the include file acl_structures.inci.pil. For a description of the gencral_acl 
structure, see the add_acl_entries entrypoint above. 



Entry: fs util $list extended acl 

This entry point returns the contents of the Extended Access Control List of a 
standard entry. 

USAGE 

declare f s__ut i 1_$ 1 i st_extended_acl entry (char (*) , char (*) , char (*) , 
ptr, ptr, fixed bin (35)); 

call f s_uti 1_$1 i st_extended_ad (dir_name, entryname, version, area_ptr, 
acl_ptr , code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

version 

is the version of the acl structure. (Output) 
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area_ptr 

is a pointer to an area where fs_util_ can allocate the general_extended_acl 
structure. If area_ptr is null, then the user wants access modes for certain 
extended ACL entries; these will be specified by the structure pointed to acl_ptr. 
(Input) 

acl_ptr 

is a pointer to the general_acl structure. (Input or Output) 

Input if area_ptr is null, then acl_ptr points to a general_extended_acl structure 

filled with access names and into which modes will be placed. 

Output: if area_ptr is non null, then acl_ptr will point to the start of a newly 
allocated general_extended_acl structure. 

code 

is a standard system status code. (Output) 
NOTES 

This interface is intended to be used only by extended entry type support routines, 
(also referenced as suffix_XXX_), in order to map an ACL mode provided to fs_util_ 
into a standard mode/ extended mode pair to be placed on the underlying standard 
entry or entries which are being used to implement the extended entry type. 

If acl_ptr is used to obtain modes for specified access names (rather than for all 
access names on an entry), then each ACL entry in the general_extended_acl structure 
either has siatus_code set to 0 and contains the entry's mode or has status_code set to 
error_table_$user_not_found and contains a mode of 0. 

The general_extended_acl structure and the named constant 
GENERAL_EXTENDED_ACL_VERSION_l are defined in the include file 
acl_structures.incl.pll. The general_extended_acl structure is described in the 
add_extended_acl_entries entrypoint described above. 



Entry: fs_util $list_switches 

This entry point returns a list of switches supported by the entry type. 
USAGE 

declare f s_ut i 1_$ 1 i st_swi tches entry (char (*) , char (*) , char (*) , ptr, 
ptr, fixed bin (35))) 5 

call fs_ut i 1_$ 1 i st_swi tches (dir_name, entryname, version, area_ptr, 
swi tch_l i st_ptr , code); 
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ARGUMENTS 



dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

version 

is the version of the switch list structure. (Input) 
area_ptr 

is a pointer to an area where fs_util_ can allocate the structure switch_list. 
(Input) 

switch_list_ptr 

is a pointer to the switch_list structure. (Output) 

code 

is a standard system status code. (Input) 
NOTES 



The list_switches structure and the named constant SWITCH_LIST_VERSION_l are 
defined in the include file suffix_info.incl.pll. 

The list_switches structure is defined as follows: 

1 switch__list aligned based (swi tch_l i st_ptr) , 

2 version char (8) , 

2 swi tch_count fixed bin, 

2 swi tch_name_count fixed bin, 

2 switches (al 1 oc_swi tch_count 

refer (switch_l i st . swi tch_count) ) , 
3 name_index fixed bin, 

3 name_count fixed bin, 

3 def aul t_value bit (1) aligned, 

3 mbzl bit (36) al igned, 

2 names (al loc_swi tch_name_count refer 

(swi tch_l i st .swi tch_name count)) char (32); 
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STRUCTURE ELEMENTS 



version 

is the current version of this structure and has the value of the named constant 
SWITCH_LIST_VERSION_l. 

switch_count 

is the number of switches defined for this entry type. 
switch_name_count 

is the total number of names of the switches; a switch can have multiple names. 
name_index 

is the index into suffix_lisL names aray of the first name for this switch. 
name_count 

is the number of names for this switch. The names for this switch are located in 
switch_list.names(name_index) through switch_list.names(name_index + name_count - 
1). 

default_value 

is the default setting for this switch when the entry is created, is the array of 
switch names. 



Entry: f s util Slist switches f or type 

This entry point returns a list of switches for a particular type of entry. 
USAGE 

declare f s_ut i 1_$ 1 i st_swi tches_f or_type entry (char (*) , char (*) , ptr, 
ptr, fixed bin (35)) ; 

call f s_ut i 1_$ 1 i st_swi tches_f or_type (type, version, area_ptr, 
swi tch_l i st_ptr , code); 

ARGUMENTS 

type 

is either the suffix if extended, or one of the name constants for standard entry 
types found in the include file suffix_info.incl.pll. (Input) 

version 

is the version of the switch_list structure. (Input) 
area_ptr 

is a pointer to an area where fs_util_ can allocate the structure switch_lisL 
(Input) 
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switch_list_ptr 

is a pointer to the switch_list structure. (Output) 

code 

is a standard system status code. (Input) 
NOTES 

The list_switches structure and the named constant SWITCH_LIST_VERSION_l are 
defined in the include file suffix_info.incl.pll. The list_switches structure is described 
in the list_switches entrypoint above. 



Entry: fs util Smake entry 

This entry point constructs a variable to a specified suffix support subroutine for a 
specified extended entry. 

USAGE 

declare f s_ut i l_$make_entry entry (char (*) , char (*) , char (*) , entry, 
fixed bin (35)) ; 

call f s_ut i l_$make_entry (dir_name, entryname, entrypoint, 
entry_to_cal 1 , code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

entrypoint 

is the name of the entrypoint that is is to be constructed. (Input) 

entry_to_call 

is the entry variable constructed. (Output) 

code 

is a standard system status code. (Output) 
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Entry: f s util Smake entry f or type 

This entry point constructs a variable to a specified suffix support subroutine for a 
specified type of extended entry. 

USAGE 

declare f s__ut i l_$make_entry_f or_type entry (char (*) , char (*) , entry, 
fixed bin (35)) ; 

call f s_ut i l_$make_entry_f or_type (type, entrypoint, entry_to_cal 1 , 
code) ; 

ARGUMENTS 

type 

is either the suffix if extended, or one of the name constants for standard entry 
types found in the include file suffix_info.incl.pll. (Input) 

entrypoint 

is the name of the entrypoint that is is to be constructed. (Input) 

entry_to_call 

is the entry variable constructed. (Output) 

code 

is a standard system status code. (Output) 



Entry: fs util Sreplace acl 

This entry point is used to replace Access Control List components for an entry. 
USAGE 

declare f s_ut i l_$repl ace_acl entry (char (*) , char (*) , ptr, bit(l), fixed 
bin (35)); 

call f s_ut i l_$repl ace_ac 1 (dir_name, entryname, acl_ptr, no_sysdaemon, 
code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 
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acl_ptr 

is a pointer to the structure general_extended_acl. (Input) 



no_sysdaemon 

is a switch that indicates whether an rw *.SysDaemon.* entry is to be put on the 
ACL of the segment after the existing ACL has been deleted and before the 
user-supplied general_acl entries are added. (Input) 
"0"b adds rw *.SysDaemon.* entry 

"l"b replaces the existing ACL with only the user-supplied general_acl. 



code 

is a standard system status code. (Output) 



NOTES 



The general_acl structure and the named constant GENERAL_ACL_VERSION_l are 
defined in the include file acl_structure.incl.pll. The general_acl structure is described 
above in the entrypoint add_acl_entries. 



Entry: f s util $replace__extended__acl 

This entry point is used to replace Extended Access Control List components for a 
standard entry. 

USAGE 

declare f s_uti l_$replace_extended_acl entry (char (*) , char (*) , ptr, 
bit (1) , fixed bin (35)) ; 

call f s_ut i l_$replace_extended_ac 1 (dir_name, entryname, acl_ptr, 
no_sysdaemon, code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

acl_ptr 

is a pointer to the structure general_extended_acl. (Input) 
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no_sysdaemon 

is a switch that indicates whether an rw *.SysDaemon.* entry is to be put on the 
ACL of the segment after the existing ACL has been deleted and before the 
user-supplied general_acl entries are added. (Input) 
"0"b adds rw *.SysDaemon.* entry 

"l"b replaces the existing ACL with only the user-supplied general_acl. 

code 

is a standard system status code. (Output) 
NOTES 

This interface is intended to be used only by extended entry type support routines, 
(also referenced as suffix_XXX_), in order to map an ACL mode provided to fs_util_ 
into a standard mode /extended mode pair to be placed on the underlying standard 
entry or entries which are being used to implement the extended entry type. 

The structure general_extended_acl and the named constant 

GENERAL_EXTENDED_ACL_VERSION_l are defined in the include file 

acl_structures.incl.pll. The structure general_extended_acl is described in the 
add_extended_acl_en tries entry point above. 



Entry: fs util $set bit count 

This entry point sets the number of bits considered useful for an entry. 
USAGE 

declare f s_ut i l_$set_b i t_count entry (char (*) , char (*) , fixed bin 
(41) , fixed bin (35) ; 

call f s_ut i l_$set_b i t_count (dir_name, entryname, bit_count, code); 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

bit_count 

is the number of bits to be considered useful in the entry. (Input) 

code 

is a standard system status code. (Output) 
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Entry: fs__util__$set max_Jength 

This entry point sets the maximum length a particular entry grow to. 
USAGE 

declare f s_uti l_$set_max_J ength entry (di r_name, entryname, max__l ength, 
code) ; 

call fs_ut i l_$set_max_l ength (char (*) , char (*) , fixed bin (35). fixed 
bin (35)); 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

max_length 

is the maximum length in words to be placed on the entry. (Input) 

code 

is a standard system status code. (Output) 



Entry: fs util $set ring brackets 

This entry point sets the ring brackets of an entry. 
USAGE 

declare f s_ut i l_$set_r i ng_brackets entry (char (*) , char (*) , (*) f i xed 
bin(3) , fixed bin (35)) 5 

call f s_ut i l_$set_r i ng_brackets (dir_name, entryname, r i ng_brackets , 
code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

ring_brackets 

are the bounds of the rings from which an entry is accessible. (Input) 
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code 

is a standard system status code. (Output) 



Entry: fs__util $set switch 

This entry sets the value of a storage system switch for an entry. 
USAGE 

declare f s_ut i l_$set_swi tch entry (char (*) , char (*) , char (*) , bit(l) 
aligned, fixed bin (35)); 

call f s_ut i l_$set_swi tch (dir_name, entryname, swi tch_name, value, 
code) ; 

ARGUMENTS 

dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

switch_name 

is the name of the switch whose value is to be set This may be either "copy," 
"complete_volume_dump," "damaged," "incremental_volume_dump," p"safety," 
"synchronized," or any switch on an extend entry type. (Input) 

value 

is the value to which the switch is to be set. (Input) 

*T'b means the switch is on 
"0" means that it is off. 

code 

is a standard system status code. It should be set to error_table_$argerr if 
switch_name is invalid. (Output) 



Entry: fs util $suffix info 

This entry point returns information about an entry's type. 
USAGE 

declare f s_ut i l_$suf f i x_i nf o entry (char (*) , char (*) , ptr, fixed 
bin (35)); 

call f s_uti l_$suf f ix_i nfo (dir_name, entryname, suf f i x_i nf o_ptr , code); 
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ARGUMENTS 
dir_name 

is the absolute pathname of the directory containing the entry. (Input) 

entryname 

is the name of the entry. (Input) 

suffix_info_ptr 

is a pointer to the suffix_info structure. (Input) 

code 

is a standard system status code. (Output) 
NOTES 

The suffix_info structure and the named constant SUFFIX_INFO_VERSION_l are 
defined in the include file suffix_info.incl.pll. 



suf f i x_i nf o 
2 version 
type 

type_name 
pi ura l_name 
f 1 ags 

3 standard_object 
3 extended_acl 

3 has_switches 
3 mb2l 
modes 

max_mode_l en 
num_r i ng_brackets 
copy_f 1 ags 
i nf o_pathname 



aligned based (suf f i x_i nf o_ptr) , 
char (8) , 

char (32) unaligned, 

char (32) unaligned, 

char (32) unaligned, 

una 1 i gned, 

bit (1) unal i gned, 

bit (1) unal i gned, 

bit (1) una 1 i gned . 

bi t (33) unal i gned, 

char (36) , 

fixed bin, 

fixed bin, 

1 i ke copy_f 1 ags , 

char (168) unaligned; 



STRUCTURE ELEMENTS 



version 

is the current version of this structure and has the value of the named constant 
SUFFIX_INF0_VERSI0N_1. 

type 

is either the suffix if extended, or one of the name constants for standard entry 
types found in the include file suffix_info.incl.pll. (Input) 
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is the singular name of the entry type (e.g., "mailbox"). 
plural_type 

is the plural name of the entry type <e.g., "mailboxes"). 
standard_object 

is set to indicate that the entry is to be handled by fs_util_ itself. 
extended_acl 

is a switch indicating whether or not the entry type supports an extended Access 
Control List. The switch should be on if the type supports extended ACLs, and 
off otherwise. 

has_switches 

is on if the entry type supports the get_switch and set_switch entries, 
mbzl 

is reserved for future use and must be zero, 
modes 

is a string containing the access modes for the entry type. This string contains 
one character for each mode bit. The position of the character in the string 
indicates which bit in the ACL represents that mode. 

max_mode_len 

is the maximum number of modes on a single entry of this type. This is used by 
the list_acl command for formatting. 

num_ring_brackets 

is the number of ring brackets on an entry. 

copy_flags 

for its format, see the copy _f lags structure described above under the copy entry 
point 

The flags configuration provided by suffix_info define what copy operations are 
valid for the extended entry type. During the copy operation, these flags are 
ANDed with the copy flags provided with the call to fs_util_. Only the 
operations allowed by suffix_info and requested by the copy call are performed. 
fs_util_ does not notify its caller that certain flags were ignored; however, the 
identity $copy these flags is computable via a call to suffix_info. 

info_pathname 

is the pathname of an info segment containing more information about the 
extended entry type, meanings of its modes, switches, and so forth. 
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Entry: f s___util $suf f ix_inf o_f or__ty pe 

This entry point returns information about the characteristics of an entry that is of a 
given type. It behaves exactly as the suffix_info en try point except that a directory and 
entry name are not used to determine the type for which suffix info is to be 
returned. 

USAGE 

declare f s_ut M_$suf f i x_i nf o_f or_type entry (char (*) , ptr, fixed 
bin (35)); 

call f s_uti l_$suf f ix_i nfo_for_type (type, suf f i x_i nf o_ptr , code); 

ARGUMENTS 

type 

is either the suffix if extended, or one of the name constants for standard entry 
types found in the include file suffix_info.incl.pll. (Input) 

suffix_info_ptr 

is a pointer to the suffix_info structure. (Input) 

code 

is a standard system status code. (Output) 
NOTES 

The suffix_info structure and the named constant SUFFIX_INFO_VERSION_l are 
defined in the include file suffix_info.incl.pll. The suffiy_info structure is described 
in the suffix_info entrypoint above. 



Name: ft menu 

The ft_menu_ subroutine allows a FORTRAN program to use the Multics menu 
facility (menu_). Through ft_menu_ a FORTRAN program may create a menu object, 
display the menu, and get a user-entered selection from a menu. Once a menu object 
has been created, the FORTRAN program can use this menu object by referencing it 
via a menu-id returned to the caller when the menu object was created or when a 
stored menu object was retrieved. 

The functionality available is provided through the various entry points defined below. 
Also refer to the FORTRAN include file at the end of this section. 
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Entry: ft menu Screate 

Utilized to create a menu object. It returns a menu identifier (menu_id) which is 
subsequently used to reference the menu object. 



USAGE 



declarations: 



character*nl 
character*n2 
character«n3 
character"! 
characters 
i nteger 
i nteger 
i nteger 
i nteger 



choi ces (ml) 
headers (m2) 
tra i 1 ers (m3) 
keys (mk) 
pad_char 
menu_f ormat (6) 
menu_needs (3) 
menu_i d 
code 



call ft_menu_$ create (choices, headers, trailers, pad_char, 
menu_f ormat , key, menu_needs, menu_id, code) 



STRUCTURE ELEMENTS 



choices 

is an array of character variables which are the text of the options that the user 
wishes to display in the menu. (Input) ni is the length, in characters, of the 
longest character string comprising the text of an option, ml is the extent of the 
array, i.e., the number of options in the menu being described. This array must 
be at least of extent 1. 



headers 

is an array of character variables to be displayed at the top of the menu. (Input) 
n2 is the length, in characters, of the longest header specified. m2 is the extent 
of the array, i.e., the number of headers (lines) desired. At least one header must 
be specified (if the first variable is set to blanks, no headers will be used). 

trailers 

is an array of trailers (displayed immediately below the menu). (Input) n3, m3, 
are analogous to n2, m2 respectively. 
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menu_format 

is an array, which specifies the format of the menu being created. (Input) Prior 
to calling this entry point, the FORTRAN programmer is responsible for setting 
the following variables: 

menu_f ormat (menu_vers i on) = version number of menu_ 

(currently, only version 1 is defined). 
menu_f ormat (max_wi dth) = maximum width of the window 

on which the menu will be displayed. 
menu_f ormat (max_hei gth) = maximum height of window 

on which menu is to be displayed. 
menu_f ormat (no_of_col umns) = number of columns to be used 

by the menu manager to display the options. 
menu_f ormat (center_headers) = 0 or 1 ; 0 - no, 1 = yes. 
menu_f ormat (center_tra i 1 ers) = 0 or 1 ; 0 = no, 1 = yes. 



pad_char 

is the character that the menu facility will display at the right and left of a 
centered header or trailer to fill out the line. (Input) 

keys 

is an array (maximum value of m4 is 61) that identifies the keystroke to be 
associated with each choice. (Input) This array must be at least as long as the 
number of choices in the menu. Each element in the array must be unique. 

menu_needs 

an array that contains menu related information on successful execution of call. 
(Output) 

Returned information: 

menu_needs (1 i nes_needed) the number of lines required 

to display the menu. 
menu_needs (wi dth_needed) the number of columns required 

to display the menu. 
menu_needs (no_of_opt i ons) the number of options defined 

in the menu. 



menu_id 

the menu identifier (i.e., the menu object "identifier"). (Output) It must not be 
altered in any way by the application program. 

code 

return code. (Output) (See Appendix B.) 
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Entry: ft menu Sdelete 

Deletes a menu object from a given value segment. (See ft_menu_$store.) 
USAGE 



declarations: 



character*l68 dir_name 

character«32 entry_name 

character*32 menu_name 

integer code 



call f t_menu_$del ete (dir_name, entry_name, menu_name, code) 
STRUCTURE ELEMENTS 



dir_name 

pathname of the directory containing the menu object. (Input) 
entry_name 

entry name of value segment containing the menu object (Input) The suffix 
"value" need not be specified. 

menu_name 

name used to identify the menu object when the menu object was stored. (Input) 

code 

return code. (Output) (See Appendix B.) 



Entry: ft menu Sdescribe 

Returns information about a menu object. It returns the number of options in the 
menu, the number of lines and number of columns required to display the menu. It 
is primarily used to determine if the menu can be displayed in a given window. 

USAGE 

dec 1 arat i ons : 

integer menu_id 
integer menu_needs (3) 
integer code 

call f t_menu_$descr i be (menu_id, menu_needs, code) 
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STRUCTURE ELEMENTS 



menu_id 

the menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input) 
menu_needs 

an array into which menu related information is returned. (Output) 
Returned information: 

menu_needs (1 i nes_needed) the number of lines required 

to display the menu. 

menu_needs (width_needed) the number of columns needed 

to display the menu. 

menu_needs (no_of_opt i ons) the number of options defined 

in the menu. 



code 

return code. (Output) (See Appendix B.) 



Entry: ft menu Sdestroy 

Invoked to delete a menu object from storage. (Not to be confused with 
ft_menu_$delete, which deletes the menu object from a value segment.) Deleting the 
menu object has no effect on the screen contents. 

USAGE 

dec 1 arat i ons: 

integer menu_id 
integer code 

call f t_menu_$destroy (menu_id, code); 



STRUCTURE ELEMENTS 



menu_id 

menu identifier returned by f t_menu_$create or f t_menu_$retrieve. (Input/Output) 
Set to an invalid value on return to prevent the old menu_id from being 
accidentally used. 

code 

return code. (Output) (See Appendix B.) 
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Entry: ft_menu $display 

Invoked to display a menu in a given window. 
USAGE 

decl arat ions: 

integer window_id 
integer menu_id 
integer code 

call f t_menu_$d i spl ay (window_id, menu_id, code) 



STRUCTURE ELEMENTS 



window_id 

a window identifier returned by ft_window_$create. (Input) If usage_mode = 0 
this argument will be ignored (see ft_menu_$init2). 

menu_id 

menu identifier returned when the menu object was created or retrieved. (Input) 

code 

return code. (Output) (See Appendix B.) 



Entry: ft menu $get choice 

Returns the choice made by the user, i.e., an integer representing either the menu 
item chosen or the function key (or its equivalent escape sequence) entered. 

USAGE 

dec 1 arat i ons : 

character*nl f unct i on_key_i nf o 
integer window_id 
integer meniMd 
integer fkeys 
integer selection 
integer code 

call f t_menu_$get_choi ce (window_id, menu_id, f unct i on_key_i nf o, 
fkeys, selection, code) 
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STRUCTURE ELEMENTS 



window_id 

a window identifier returned by ft_window_$create. (Input) If usage_mode = 0 
this argument will be ignored, (see f t_menu_$init2) 

menu_id 

menu identifier returned by f t_menu_$create or ft_menu_$retrieve. (Input) 
f unction_key_inf o 

a character variable (nl as required) used to specify the role of function keys (if 
they exist for the terminal being used) or an equivalent set of escape sequences if 
the terminal does not have function keys or not the function keys required by 
the application. (Input) The objective is to let the application use the terminal's 
function keys if possible, else specify key sequences to be used to simulate 
function keys. Each character in the string corresponds to one function key. If 
the character is a space, then it is not relevant if the corresponding function key 
exists or not. If the character is not a space, that character will be used to 
simulate a function key if the terminal does not have function keys. If the 
terminal does not have a function key for every non-space character in the 
string, then function keys will be simulated. Thus, the string " ?p q" means that 
the caller does not care whether the terminal has function key 0 or 3, but the 
caller does wish to use function keys 1,2, and 4. If any of these 3 function keys 
is not present on the terminal, then esc-? will substitute for Fl, esc-p will 
substitute for F2, and esc-q will substitute for F4. 

fkeys 

if fkeys = 1 user entered a function key or escape sequence if fkeys = 0 user 
selected an option (Output) 

selection 

is an integer representing the choice made by the user. (Output) If the user has 
chosen an option, it is a number between 1 and the highest defined option. If 
the user has entered a function key, or escape sequence simulating a function key, 
it is the number associated with the function key. 



code 

return code. (Output) (See Appendix B.) 
Entries: ft menu $initl, ft_menu $init2 



These must be the first calls made to the menu manager. They set up the necessary 
environment for the menu application and return information concerning the user i/o 
window. 
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USAGE 

declarations: 

integer code 
integer usage_mode 

call f t_menu_$ i n i 1 1 () 

call f t_menu_$ i n i t2 

(usage_mode, user_wi ndow_] i nes,user_wi ndow_col umns, 
user_wi ndow_i d , code) 

STRUCTURE ELEMENTS 



usage_mode 

usage_mode = 0 means that the caller does not wish to do any window 
management at all. (Input) When he/she wishes to display a menu, the window 
required will be automatically created. This means that the application will operate 
in a two window mode, the window containing the menu, and the user_io 
window. Both windows will be managed automatically for the user. If the user 
specifies this mode, all calls to the ft_window_ subroutine will be ignored and 
will return an appropriate error code. See Error Code Handling (Appendix B), 
below. All calls to the ft_menu_ subroutine that require a window identifier will 
ignore the user provided window_id. 

usage_mode = 1 means that the user wishes to define the number and 
characteristics of the windows to be used in the application. Thus, calls to 
ft_window_ will be supported and, for the entry points of ft_menu_ that require 
a window identifier, the caller must use a legal window_id (returned by 
f t_window_$create). 

user_window_lines 

the number of lines (rows) in the user i/o window at the time the user invokes 
f t_menu_$init (which must be the first call to the menu manager in the 
application). (Output) Undefined if usage_mode = 0. 

user_window_columns 

the number of columns of the user i/o window when f t_menu_$init invoked. 
(Output) Undefined if usage_mode = 0. 

user_window_id 

window identifier of the user i/o window. (Output) Undefined if usage_mode = 
0. 

code 

return code (See Appendix B.) (Output) 



2-323 



AG93-05 



ft_menu_ ft_menu_ 



Entry: ft__menu__$list 

Used to list the menu object(s) stored in value segment. The names selected are those 
that match a user provided string. 

USAGE 

declarations: 

character»l68 dir_name 

character*32 names_array (ml) 

character*32 entry_name 

character*32 match_string 

integer no_of_matches 

integer code 



call f t_menu_$ 1 i st (dir_name, entry_name, match_str i ng , 
no_of_matches , names_array, code) 



STRUCTURE ELEMENTS 



dir_name 

pathname of directory containing the menu object. (Input) 



entry_name 

entry name of value segment containing the menu object. (Input) The suffix 
"value" need not be specified. 

match_string 

% character variable that is to be used as the selection criteria to determine what 
menu object, if any, is contained in the specified value segment that match (or 
contain) this string. (Input) If set to space(s), all names returned. 

no_of_matches 

the number of matches found. (Output) If none, then is is 0. 



names_array 

an array, of extent ml. (Output) The user should insure that ml is sufficiently 
large to contain ail matches thai may be found. Contains the names of all menu 
objects, in the specified value segment, that match the character string match_string. 



code 

return code. (Output) (See Appendix B.) 
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Entry: ft_menu Sretrieve 

Used to retrieve a menu object previously stored via the ft_menu_$store. Once 
retrieved, the user can reference the menu object via the menu identifier (menu_id). 

USAGE 

decl arat i ons: 

character*! 68 dir_name 
character*32 entry_name 
character*32 menu_name 
integer menu_id 
integer code 

call f t_menu_$retr i eve (dir_name, entry_name, menu_name, menu_id, 
code) 

STRUCTURE ELEMENTS 



dir_name 

pathname of the directory containing the menu object. (Input) 
entry_name 

entry name of value segment containing menu object. (Input) The suffix "value" 
need not be specified. 

menu_name 

name of the menu object used when the object was stored. (Input) 
menu_id 

is the menu id returned by the call. (Output) It is used as the menu object 
identifier. 

code 

return code. (Output) (See Appendix B.) 
Entry: ft menu Sstore 

Used to store a menu object in a specified value segment 
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USAGE 

dec larations: 



character*l68 dir_name 

character«32 entry_name 

character*32 menu__name 

integer create_seg 

integer menu_id 

integer code 



call ft_menu_$ store (di r_name,entry_name, menu_name, create_seg, 
menu_id, code) 



STRUCTURE ELEMENTS 



dir_name 

pathname of directory into which the menu object is to be placed. (Input) 
entry_name 

entry name of value segment into which the menu object is to be placed. (Input) 
The suffix "value" need not be specified. 

menu_name 

it is the name to be assigned to the stored menu object (Input) 
create_seg 

create seg = 0 means do not store if value segment identified by entry_name does 
not already exist. (Input) 

create_seg = 1 means create value segment, if it does not already exist, and store 
menu object in it. 

menu_id 

it is the menu object identifier returned when ft_menu_$create or f t_menu_$retrieve 
was called. (Input) 

code 

return code. (Output) (See Appendix B.) 
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Entry: ft menu Sterminate 

Must be the last call to the menu manager in the menu application. It will remove 
the special environment created by ft_menu_$initl and ft_menu_$init2. 

USAGE 

declarations: none 

call f t_menu_$termi nate () 
FORTRAN INCLUDE FILE 

This include file contains the following declarations: 

external ft_menu_$ create (descriptors) 

external f t_menu_$del ete (descriptors) 

external f t_menu_$descr i be (descriptors) 

external ft_menu_$ destroy (descriptors) 

external f t_menu_$d i spl ay (descriptors) 

external f t_menu_$get_choi ce (descriptors) 

external f t_menu_$ i n i t 1 (descriptors) 

external f t_menu_$ i ni t2 (descriptors) 

external f t_menu_$ 1 i st (descriptors) 

external f t_menu_$retr i eve (descriptors) 

external ft_menu_$ store (descriptors) 

external f t_wi ndow_$ change (descriptors) 

external f t_wi ndow_$create (descriptors) 

external f t_wi ndow_$destroy (descriptors) 

integer menu_version 

integer max_width 

integer max_height 

integer no_of_col umns 

integer lines_needed 

integer width_needed 

integer no_of_opt i ons 

integer center_headers 

integer center_tra i 1 ers 

integer user_wi ndow_J d 

integer user_wi ndow_l i nes 

integer user__wi ndow_col urnns 

parameter (menu_vers i on = 1) 

parameter (max_width = 2) 

parameter (max_height = 3) 

parameter (no_of_col umns = h) 
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parameter (center_headers = 5) 

parameter (center_tra i 1 ers = 6) 

parameter (1 i nes_needed = 1) 

parameter (wi dth_needed = 2) 

parameter (no_of_opt i ons = 3) 



Name: ft window 

This is the basic video interface subroutine to be used by FORTRAN to 
create/ destroy /change windows. (This subroutine should not be called if usage_mode = 
0 (see ft_menu_$init2)). 

Its facilities are available through the following entry points. 



Entry: ft window Schange 

This entry point is used to change the size of an existing window. The size of a 
window can always be "shrunk", however it can be increased only it does not overlap 
with another defined window. (This entry point should not be called if usage_mode = 
0 (see ft_menu_$init2).) 

USAGE 

dec 1 arat i ons : 

integer window_id 

i nteger f i r st_1 i ne 

integer height 

integer code 

call f t_wi ndow_$ change (window_id, first_line, heigth, code) 



STRUCTURE ELEMENTS 



window_id 

window identifier returned by ft_window_$create (or by f t_menu_$init in the case 
of the user i/o window). (Input) 

first_line 

new first line number for the window being changed. (Input) Positive integer. 

height 

new height for the window being changed. (Input) Positive integer. 
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code 

return code. (Output) (See Appendix B.) 



Entry: ft window Sclear window 

Used to clear a specified window. 
USAGE 

declarations: 

integer window_id 
integer code 

call f t_wi ndow_$ clear window (window id, code) 



STRUCTURE ELEMENTS 



window_id 

The window identifier (returned by ft_window_$create) of the window to be 
cleared. (Input) 



code 

return code. (Output) (See Appendix B.) 



Entry: ft window $create 

Used to create a new window on the terminal screen. (This entry point should not be 
called if usage_mode = 0.) (see ft_menu_$init2) 



USAGE 



decl arat ions: 



character*32 switch_name 

integer window_id 

i nteger f i rst__l i ne 

integer height 

:eger code 



call f t_wi ndow_$ create (first_line, height, switch_name, 
window id, code) 
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STRUCTURE ELEMENTS 
first_line 

is the line number where the window is to start. (Input) 
height 

the number of lines used by the window, i.e., its height. (Input) 
switch_name 

the name that the caller wishes to associate with the switch. (Input) (The caller 
may use the switch name, for example, in the FORTRAN "open" statement.) 

window_id 

the returned id of the window just created. (Output) It must not be altered in 
any way by the application program. 

code 

return code. (Output) (See Appendix B.) 
Entry: ft window $destroy 

Used to destroy a previously created window. (This entry point should not be called 
if usage_mode = 0 (see ft_menu_$init2).) 

USAGE 

decl arat ions: 

i ntsgsr window 'd 
integer code 

call f t_wi ndow_$ destroy (window_id, code) 
STRUCTURE ELEMENTS 
window_id 

window identifier (returned by the f t_window_$create). (Input /Output) It is reset 
to an illegal value by this call. 

code 

return code. (Output) (See Appendix B.) 
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FORTRAN MENU APPLICATION EXAMPLES 

In the following two FORTRAN examples, a "Message" menu application is created 
that allows you to display, print, discard, or forward messages. Example 1 is a simple 
FORTRAN program that interfaces with the Multics menu manager via the ft_menu_ 
routine. Note in Example 1 that window management functions are called automatically 
through arguments in the ft_menu_$init2 subroutine. 

Example 2 is a FORTRAN program that interfaces with the Multics menu manager 
through ft_menu_routine; in example 2, however, window management functions are 
performed by the ft_window_ routine. 

EXAMPLE 1: 

In this example, all window management is done automatically. 

subroutine testcasel () 

% include ft_menu_dcls 

external f t_menu_$ i ni t 1 (descriptors) 
external f t_menu_$ i ni t2 (descriptors) 
character*15 choices (6) 
character*! 2 headers (1) 
character*27 trailers (1) 
character*l keys (6) 
character* 1 68 dir name 



Ci"!2**2CtSr*^32 

character*32 
character^ 2 
character *32 
character*9 




i nteger 
i nteger 
i nteger 
i nteger 
i nteger 
i nteger 
i nteger 
i nteger 
i nteger 
i nteger 
i nteger 



2ero 



external com_er r_ (descr i ptors) 



i nteger 
i nteger 
i nteger 



too_f ew_keys 
bad_arg 

key s_not_un i que 
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ME = "testcasel" 
zero = 0 

choices (1) - "Display Message" 
choices (2) = "Print Message" 
choices (3) = "Discard Message" 
choices (h) = "Forward Message" 
choices (5) = "Reply Message" 
choices (6) = "List Messages" 
headers (1) = "READ MAIL" 

trailers (1) = "Press Fl (or esc-q) to quit" 

keys(l) = "1" 

keys (2) = "2" 

keys (3) = "3" 

keys (4) = "V 

keys (5) = "5" 

keys (6) = "6" 

pad_char = "-" 

menu_f ormat (menu_vers i on) = 1 
menu_format (max width) — 79 
menu_f ormat (max_hei ght) = 10 
menu_f ormat (no_of_col umns) = 2 
menu_format (center_headers) = 1 
menu_f ormat (center_tra i 1 ers) = 1 



code = 0 

usage_mode = 0 ! Window management will be done automatically 
! by the system, i.e., usage_mode is set to 0. 
! by the system, i.e., usage_mode is set to 0. 

call f t_menu_$ i n i t 1 () 

ca 1 1 f t_menu_$ i n i t2 (usage_mode, user_wi ndow_l i nes , user_wi ndow_col umns , 

user_wi ndow_i d , code) 
! Calling f t_menu_$ i n i t MUST 

! be the first call to ft_menu_ in the program, 
if (code .eq. zero) go to 5 

call com_err_ (code, ME, " (calling f t_menu_$ i ni t2) ") 

print, "Unable to set up the appropriate environment for the application." 
go to 999 

c The following calls to cv_error_$name are used retrieve and store 
c the error codes associated with certain errors of interest returned 
c by calls to the menu manager or the system. 

5 call cv_error_$name ("error_tabl e_$bad_arg" , bad_arg, code) 
if (code *eq, zero) go to 10 

call com_err_ (code, ME, !! error_tab 1 e_$bad_arg !! ) 
go to 999 

10 call cv_er ror_$name ("menu_et_$too_f ew_keys" , too_f ew_keys , code) 
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if (code .eq. zero) go to 20 

call com_err_ (code, ME, "menu__et__$too_f ew = keys") 
go to 999 

20 call cv_error_$name ("menu_et_$keys__not_unique", keys_not_un i que, code) 
if (code .eq. zero) go to hO 

call com_err_ (code, ME, "menu_et_$keys_not_uni que") 
go to 999 

^0 call ft_menu_$ create (choi ces , headers , tra i 1 ers , pad_char ,menu_f ormat , 
& keys, menu_needs ,menu_id, code) 

c This call creates the menu object and returns the menu object identifier, 
c "menu_id". 

if (code .eq. zero) go to hS 

call com_err_ (code, ME, " (calling f t_menu_$ceate) ") 
print, "The menu could not be created." 
go to 999 

c The created menu is now stored for future use. 

kS dir_name = ">udd>m>ri" ! pathname of directory 

entry_name = "menus_seg" ! entry name of "value" segment 

menu_name = "f t_read_ma i l_menu" ! name of menu 

create_seg = 1 ! create "value" seg if it does not already exist. 

call ft_menu_$ store (dir_name, entry_name, menujiame, 

create_seg, menu id, code) 
if (code .eq. zero) go to 50 

call com_err_ (code, ME, " (calling f t_menu_$store) ") 

print, "The menu could not be stored." 

go to 999 
50 window_id = 0 

call f t_menu_$d i spl ay (wi ndow_i d ,menu_i d , code) ! This call displays 

! the menu in its own window at top of screen. Since the usage_mode 

! was set to 0, the program does not have to create the window 

! before calling f t_menu_$d i spl ay . The window_id argument is ignored. 

if (code .eq. zero) go to 60 

call com_err_ (code, ME, " (calling f t_menu_$di spl ay) ") 
print, "The menu could not be displayed." 
go to 999 

60 funct ion_key_i nfo = "q" ! Defines the function key requirements, i .e, 

! if the terminal has function key 1 (Fl) then Fl will be used 
! to "quit", otherwise "esc_q" will be used to "quit". 

61 cal 1 f t_menu_$get_cho i ce (wi ndow_i d,menu_i d, funct i on_key_i nf o, f keys , 
& selection, code) 
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c This call accepts the user input from the menu. On return, the variable 

c "selection" will contain a number (1, 2, 3 » or h) representing the option 

c chosen by user . 

c Note: if the user entered anything other than 1 or 2 or 3 or k 

c the terminal "beeped", and the user input was ignored, 

c Since usage_mode is 0, the window_id argument is ignored. 

if (code .eq. zero) go to 90 

if (code .ne. too_f ew_keys) go to 70 

call com_err_ (0, ME, "Number of keys less than number of options.") 
go to 999 

70 if (code .ne. keys_not_un i que) go to 80 

call com_err_ (0, ME, "Option keys not unique.") 
go to 999 

80 call com_err_ (code, ME, " (calling f t_menu_$get_choi ce) . 

An internal programming error has occurred.") 

go to 999 

90 if (fkeys .eq. zero) go to 110 
; f (fie no t r\ i nn 

V ' /- .—-i- ■/ 3 — ■ 

print, "An internal program error has occurred. Quitting." 
go to 999 

100 if (selection .ne. 1) go to 6l 

print, "You entered ""Fl"" or ""esc q"". Quitting." 

go to 999 
110 print 103, sel ect i on 
103 format ("You selected option "il) 

go to 50 

999 call ft menu $terminate() 
return 
end 



EXAMPLE 2: 

In this example, FORTRAN interfaces with the Multics menu manager and the Multics 
window manager via the ft_menu_ and ft_window_ subroutines. 

subroutine testcase2 () 

% include f t_menu_dc 1 s 

external f t_menu_$ i n i t 1 (descriptors) 

externa 1 f t_menu_$ i ni t2 (descr i ptors) 

external f t_wi ndow_$c 1 ear_wi ndow (descriptors) 

character?*^ cho i ces_one (2) 

character^ I choi ces_three {k) 

character*^ 1 headers (1) 

character**^ trailers (1) 
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character*! 


keys (6) 


character*l68 


d i r_name 


character«32 


entry_name 


character*32 


menu_name 


character&12 


function key info 


character*32 


matches tr i ng 


character«32 


names_array (10) 


character "32 


swi tch name 


character*9 


ME 


i nteger 


create seg 


i nteger 


no of matches 


i nteger 


window idl 


i nteger 


window i d 2 


i nteger 


f keys 


i nteger 


se 1 ect i on 


i nteger 


usage_mode 


i nteger 


menu_f ormat (6) 


i nteger 


menu_needs_one (3) 


i nteger 


menu_needs_two (3) 


i nteger 


menu needs three (3) 


i nteger 


curr window id 


i nteger 


menu_id 1 


i nteger 


menu_id2 


i nteger 


menu_i d3 


i nteger 


code 


i nteger 


zero 


external ccm_er 


t_ (descr i ptors) 


i nteger 


bad_wi ndow_i d 


i nteger 


nonexi stent_wi ndow 


i nteger 


i nsuf f_room_f or_wi ndow 



ME = "testcase2" 
zero = 0 



choices_one (1) = "Read Mail" 
choices_one (2) = "Send Mail" 
choices_three (1) = "Send New Messsage" 
choices_three (2) = "Send Deferred Message" 
choi ces_three (3) = "Print Sent Message" 
choi ces_three (k) = "Save Sent Message" 

trailers (1)= "Fl (or esc-q) - quit ; F2 (or esc-f) = first menu" 

keys(l) = "1" 

keys (2) = "2" 

keys (3) - "3" 

keys (if) = "V 

keys (5) = "5" 

keys (6) = "6" 

pad_char = "-" 
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menu_f ormat (menu_vers i on) = 1 
menu_f ormat (max_wi dth) = 79 
menu_f ormat (max_hei ght) = 8 
menu_f ormat (no_of_col umns) = 2 
menu_f ormat (center_headers) = 1 
menu_f ormat (center_tra i 1 ers) = 1 

code = 0 

call f tjmenu_$ i n i 1 1 () 

usage_mode = 1 Window management will be done by user 
cal 1 f t_menu_$ i ni t2 (usage_mode, user_wi ndow_l i nes,user_wi ndow_col umns , 
& user_wi ndow_id,code) Calling f t_menu_$ i n i t MUST be the 

first call to ft_menu_ in the program. 

if (code .eq. 0) go to 5 

call com_err_ (code, ME, " (calling f t_menu_$ i n i t) ") 
print, "Unable to set up the appropriate environment for the 
& appl ication." 

go to 999 

c The following calls to cv_error_$name are used retrieve and store 

c the error codes associated with certain errors of interest returned 
c by calls to the menu manager or the system. 

5 call cv_error_$name ("video_et_$bad_wi ndow_i d" , bad_wi ndow__id, code) 
if (code .eq. zero) go to 10 

call com_err_ (code, ME, "v i deo_et_$bad_wi ndow_i d") 
go to 999 

10 call cv_er ror_$name ("vi deo_et_$nonex i stent_wi ndow" , 

nonex i stent wi ndow, code) 
if (code .eq. zero) go to 20 

call com_err_ (code, ME, "video_et_$nonex i stent_wi ndow") 
go to 999 

20 call cv_er ror_$name ("vi deo_et_$ i nsuf f_room_f or_wi ndow" , 

6 i nsuf f_room_for_wi ndow, code) 
if (code .eq. zero) go to hO 

call com_err_ (code, ME, "vi deo_et_$ i nsuf f_room_for_wi ndow") 
go to 999 

c Create first menu 

1+0 headers (1) = "MULTICS MAIL" 

cal 1 f t__menu_$ create (choices_one, headers, trai lers,pad_char ,menu_f ormat, 
& keys,menu_needs_one,menu_idl ,code) 

c This call creates the menu object and returns the menu object identifier, 
c This menu is referenced by menu_idl. 
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if (code .eq. 0) go to 1+1 

call com_err_ (code, ME, 11 (calling f t_menu_$ceate) ") 
print, "The first menu could not be created." 
go to 999 

c For the second menu use a menu object which was stored in a "value" seg. 
c First determine if menu object exists. 



1+1 dir_name = ">udd>m>ri" 
entry_name = "menus_seg" 
match_string = "f t_read_ma i l_menu" 

cal 1 f t_menu_$l ist (d i r_name, entry_name,match_str i ng, no_of_matches , 
& names_array ,code) 

if (code .eq. zero) go to 1+2 

call com_err_ (code, ME, " (calling f t_menu_$ 1 i st) ") 
go to 999 

1+2 if (no_of_matches .eq. zero) then 
print, "Stored menu not found." 
go to 999 
el se 

if (no_of_matches .eq. 1) go to 1*3 
print, "Internal error. Quitting." 
go to 999 
end i f 



c Retrieve stored menu. 



I, o , -« _ ii** -j : 1 II 



hj inSniJ name — • L i cau ma i i iilClIU 

cal 1 f t_menu_$retr ieve (di r_name,entry_name,menu_name,menu_id2,code) 
if (code .eq. zero) go to kk 

call com_err_ (code, ME, " (calling f t_menu_$retr i eve) ") 
go to 999 

c Get attributes of retr i eved menu. 

hk call f t_menu_$descr i be (menu_i d2 ,menu_needs_two, code) 
if (code .eq. zero) go to k$ 

call com_err_ (code, ME, " (calling f t_menu_$descr i be) ") 
go to 999 

c Create third menu 



1+5 headers (1) = "SEND MAIL" 

call f t_menu_$create (cho i ces_three, headers, tra i 1 ers , pad_char , 
& menu_f ormat , keys , menu_needs_three , menu__i d3 » code) 

if (code .eq. 0) go to 50 

call com_err_ (code, ME, " (calling f t_menu_$ceate) ") 
print, "The third menu could not be created." 
go to 999 
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50 curr_wi ndow_id = -1 "-1" indicates that there is no current menu 

being displayed; otherwise, curr_wi ndow_id 
contains the menu window id 

52 call change_menu (user_wi ndow_i d, curr_wi ndow_i d ,menu_i d 1 ,menu_needs_one, 

5 user_wi ndow_l ines,window_idl .code) 
if (code) 51.53,51 

51 call com_err_ (code, "change_menu" ," I nterna 1 error while changing menus.") 
go to 999 

53 call f t_wi ndow_$cl ear_wi ndow (user_window_id, code) 

60 call get_choice (menu_i d 1 ,wi ndow_idl , fkeys , sel ect i on, code) 

c This call accepts the user input from the menu. On return, the variable 

c "selection" will contain a number (0, 1, 2) representing the option or 

c the function key (or its equivalent escape sequence) entered by the user. 

c If fkeys = 1 then the user entered Fl or F2 (or esc-q or esc-f) : 

c if Fl (or esc-q) was entered, then selection = 0 

c if F2 (or esc-f) was entered, then selection = 1 

q jf f keys — 0 then the user selected option? 

c if first option was chosen, then selection = 1 

c if second option was chosen, then selection = 2 

c Note: if the user entered anything other than Fl or F2 or 1 or 2 

c the terminal "beeped", and the user input was ignored. 

if (code .eq. zero) go to 70 

call com_err_ (0, "get_choi ce" , "Internal program error 

while getting user choice") 

go to 999 

70 if (fkeys .eq. zero) go to 90 user selected an option 
if (fkeys .eq. 1) then 
go to 80 user entered function key 
else Something is wrong 

print, "An internal program error has occurred. Quitting." 
go to 999 
end i f 

80 go to (81,82), selection 

call com_err_ (code, ME, "An internal program has occurred. Quitting.") 
go to 999 

81 print, "Exiting" (user has entered Fl or esc-q. Wants to exit) 
go to 999 

82 print, "You already are in the first menu." User want to go to 

first menu 

go to 60 

90 go to (100,170), selection Display either "Read Mail" or "Send Mail" 

menu 

call com_err_ (code, ME. "Internal program error. Quitting.") 
go to 999 

100 call change_menu (user_wi ndow_i d,wi ndow_i d 1 ,menu_i d2,menu_needs_two, 

6 user_window lines, window id2, code) 
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if (code ,eq. zero) go to 110 

call com_err_ (code, "change_menu" , "Internal error occurred 

while switching menus") 

go to 999 

110 call get_choice (menu_id2, window_id2, fkeys, selection, code) 
if (code .ne. zero) then 

call com_err_ (code, "get_choice", "Internal error 

while getting user choice") 

go to 999 
end i f 

go to (160, 150) , fkeys + 1 

call com_err_ (code, ME, "Internal program error. Quitting.") 
go to 999 

150 go to (151»152), selection user entered function key 
go to 110 

151 print, "Exiting at your request" 
go to 999 

152 curr_wi ndow_i d = window_id2 
go to 52 

160 print 300, selection 

300 format ("You selected option "il) 
go to 1 10 

c User chose "Send Mail" option 

170 call change_menu (user_wi ndow_i d, wi ndow_i dl ,menu_i d3,menu_needs_three, 
& user_w i ndow_1 i nes,wi ndow_id2 , code) 

if (code) 171*180,171 

171 call com_err_ (code, "change_menu" , "Internal error 

while changing menus") 

go to 999 

180 call get_choice (menu_i d3,wi ndow_i d2 , fkeys, sel ecti on, code) 
if (code) 181,190,181 

181 call com_err_ (code, "get_choi ce" , "Internal error 

while getting user choice") 

go to 999 
190 go to (210,200), fkeys + 1 

print, "Internal error. Quitting" 
go to 999 

200 go to (201,202), selection 
go to 180 

201 print, "Exiting at your request." 
go to 888 

202 curr_wi ndow_id = window_id2 
go to 52 

210 print 301, selection 

301 format ("You selected option "il) 
go to 180 

c Delete second menu from the value seg. 
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888 call f t_menu_$del ete (di r_name,entry_name,menu_name,code) 
if (code .eq. 2ero) go to 999 

print, "Menu could not be deleted from value segment." 
999 call f t_menu_$termi nate () 
return 
end 

subroutine get__choice (menu_i d,wi ndow_i d, fkeys, sel ect i on, code) 
external f t_menu_$get_choi ce (descriptors) 



character^ f unct i on_key_i nf o 

integer fkeys 

integer selection 

integer menu_id 

integer window_id 

integer code 

code - 0 



f unct i on_key_i nf o - "qf" Defines the function key requirements, i .e, 
if the terminal has function keys 1 and 2 (F 1 and F2) then Fl 
will be used to "quit" and F2 to switch to the first menu, 
otherwise "esc_q" will be used to "quit" and "esc-f" to switch 
to the f i rst menu 

cal 1 f t_menu_$get_choi ce (wi ndow_i d,menu_i d, f unct i on_key_i nf o, fkeys, 
& select ion, code) 

return 
end 

subrout i ne change_menu (user_wi ndow_id,curr_wi ndow_id,menu_id,menu_needs, 

user_wi ndow_l i nes,wi ndow_i d , code) 

external f t_wi ndow_$change (descriptors) 
external f t_wi ndow_$ create (descriptors) 
external f t_wi ndow_$destroy (descriptors) 
external f t_menu_$d i spl ay (descriptors) 
external com_er r_ (descriptors) 



character*32 switch_name 

integer menu_needs (3) 

integer user_wi ndow_i d 

integer user_wi ndow_col umns 

i nteger user_w i ndow_l i nes 

integer cur r_w I ndow_ I d 

integer menu_id 
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integer wi ndow_id 

integer code 

i nteger f i rst_l i ne 

integer height 

parameter (1 i nes_needed = 1) 



c Destroy the current menu-window 

if (curr_wi ndow_id + 1) 90,100,90 
90 call f t_wi ndow_$destroy (curr_wi ndow_id,code) 
if (code) 999,100,999 

c Change the size of the user i/o window to accomodate the new menu-window 

100 first_line = 1 + menu_needs (1 i nes_needed) 

height = user_wi ndow_l i nes - menu_needs (1 i nes_needed) 

call f t_wi ndow_$change (user_window_id,f i rst_l ine, height, code) 

if (code) 999.110,999 

c Create window for new menu 

110 switch_name = "menu_wi ndow" 

cal 1 f t_wi ndow_$create (1 ,menu_needs (1 i nes_needed) , swi tch_name,wi ndow_i d, 
& code) 

if (code) 999,120,999 

c Display the menu in the menu-window 

120 call f t_menu_$d i spl ay (wi ndow_i d ,menu_i d , code) 

999 return 
end 



Name: generic math 

The generic_math_ subroutine is used to perform basic arithmetic operations on the 
generic numeric data types. The operations that can be performed are: addition, 
subtraction, multiplication, division, and negation. There are separate entrypoints for 
each variation of the types: real and complex, binary and decimal. 
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Entry: generic math__$negate decimal 

This entrypoint negates a generic decimal number. 
USAGE 

declare gener i c_math_$negate_dec ima 1 entry (b i t (576) , bit (576)); 
call gener i c_math__$negate__dec ima 1 (numl, result); 
ARGUMENTS 
numl 

is a generic decimal number. (Input) 
result 

is the generic decimal value that is the negation of numl. (Output) 

Entry: generic__math_$negate = decimal = complex 

This entrypoint negates a generic complex decimal number. 

USAGE 

declare gener i c_math_$negate_dec ima l_compl ex entry (bi t (1 152) , 
bit (1 152)) ; 

call gener i c_math_$negate_dec i mal_compl ex (numl, result); 

ARGUMENTS 

numl 

is a generic complex decimal number. (Input) 
result 

is the generic complex decimal value that is the negation of numl. (Output) 

Entry: generic math $add decimal 

This entrypoint adds two generic decimal numbers. 
USAGE 

declare gener i c_math_$add_dec i ma 1 entry (b i t (576) , bit (576), bit (576)); 

««1 1 — ~- ! „ 4- U C ->^/J ri ^ — I 1 Luml miim*) r a c- I I 1 +• > . 

V, a I I y EM&i i v._ino u 1 1 y auu_u &\» i ma i \i iuiii i , 1 1 um<. , i w o u i \.j , 
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ARGUMENTS 
numl 

is a generic decimal number. (Input) 
num2 

is a generic decimal number. (Input) 
result 

is the generic decimal value that is the result of adding numl and num2. 
(Output) 



Entry: generic math $add__decimal complex 

This entrypoint adds two generic complex decimal numbers. 
USAGE 

declare gener i c_math_$add_dec imal_compl ex entry (b i t (1 152) , bit (1152), 
bit (1152)); 

call gener i c_math_$add_dec i ma l_comp lex (numl, num2, resul t) ; 

ARGUMENTS 

numl 

is a generic complex decimal number. (Input) 
num2 

is a generic complex decimal number. (Input) 
result 

is the generic complex decimal value that is the result of adding numl and num2. 
(Output) 



Entry: generic math $subtract decimal 

This entrypoint subtracts two generic decimal numbers. 
USAGE 

declare gener ic__math_$subtract_decimal entry (bi t (576) , bit(57&)» 
bit (576)); 

call gener ic_math_$subtract_decimal (numl, num2, result); 
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ARGUMENTS 
numl 

is a generic decimal number. (Input) 
num2 

is a generic decimal number. (Input) 
result 

is the generic decimal value that is the result of subtracting numl and numl 
(Output) 



Entry: generic math $subtract decimal complex 

This entrypoint subtracts two generic complex decimal numbers. 
USAGE 

declare aener i c_math_$subtract_dec imal_compl ex entry (b i t (1 152) s 
bit(1152) , bit (1 152)) ; 

call gener i c_math_$subtract_dec ima l_compl ex (numl, num2, result); 

ARGUMENTS 

numl 

is a generic complex decimal number. (Input) 
num2 

is a generic complex decimal number. (Input) 
result 

is the generic complex decimal value that is the result of subtracting num2 from 
numl. (Output) 



Entry: generic math__$multiply decimal 

This entrypoint multiplies two generic decimal numbers. 
USAGE 

declare gener i c_math_$mul t i pi y_decimal entry (b i t (576) , bit(576), 
bit (576)); 

call gener i c_math_$mul t i pi y_dec ima 1 (numl, num.2, result); 



2-344 



AG93-05 



generic_math_ 



generic_math_ 



ARGUMENTS 
numl 

is a generic decimal number. (Input) 
num2 

is a generic decimal number. (Input) 
result 

is the generic decimal value that is the result of multiplying numl and numl 
(Output) 



Entry: generic math Smultiply decimal complex 

This entrypoint multiplies two generic complex decimal numbers. 
USAGE 

declare gener i c_math_$mul t i pi y_decimal_compl ex entry (b i t (1 152) , 
bit (1 152) , bit (1152)) ; 

call gener i c_math_$mul t i pi y_decimal_compl ex (numl, num2, result); 

ARGUMENTS 

numl 

is a generic complex decimal number. (Input) 
num2 

is a generic complex decimal number. (Input) 
result 

is the generic complex decimal value that is the result of multiplying numl by 
num2. (Output) 



Entry: generic math Sdivide decimal 

This entrypoint divides two generic decimal numbers. 
USAGE 

declare gener i c_math_$d ivi de_dec imal entry (b i t (576) , bit (576), 
bit (576)); 

call gener i c_math_$d i v i de_dec imal (numl, num2, result); 
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ARGUMENTS 
numl 

is a generic decimal number. (Input) 
num2 

is a generic decimal number. (Input) 
result 

is the generic decimal value that is the result of dividing numl by numl 
(Output) 

Entry: generic math Sdivide decimal complex 

This entrypoint divides two generic complex decimal numbers. 
USAGE 

declare gener i c_math_$d i v i de_dec ima l_comp 1 ex entry (b i t (1 152) , bit (1152), 
bit (1152)7; 

call gener i c_math_$d i vi de_dec imal_compl ex (numl, num2, result); 

ARGUMENTS 

numl 

is a generic complex decimal number. (Input) 
num2 

is a generic complex decimal number. (Input) 
result 

is the generic complex decimal value that is the result of dividing numl by numl 
(Output) 

Entry: generic math Snegate binary 

This entrypoint negates a generic binary number, 
USAGE 

declare gener i c_math_$negate_bi nary entry (bi t (108) , b i t ( 1 08) ) ; 
call gener i c_math_$negate_bi nary (numl, result); 
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ARGUMENTS 
numl 

is a generic binary number. (Input) 
result 

is the generic binary value that is the negation of numl. (Output) 

Entry: generic math Snegate binary complex 

This entrypoint negates a generic complex binary number. 
USAGE 

declare generi c_math_$negate_bi nary_comp1ex entry (bi t (252) , bit (252)); 
call generic_math_$negate_binary_complex (numl, result); 
ARGUMENTS 
numl 

is a generic complex binary number. (Input) 
result 

is the generic complex binary value that is the negation of numl. (Output) 

Entry: generic math $add binary 

This entrypoint adds two generic binary numbers. 
USAGE 

declare gener i c_math_$add_b i nary entry (bi t (108) , bit(108), bit(108)); 

call gener i c_math_$add_b i nary (numl, num2, result); 

ARGUMENTS 

numl 

is a generic binary number. (Input) 
num2 

is a generic binary number. (Input) 
result 

is the generic binary value that is the result of adding numl and num2. (Output) 
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Entry: generic math_$add_binary complex 

This entrypoint adds two generic complex binary numbers. 
USAGE 

declare gener ic_math_$add_bi nary_compl ex entry (b i t (252) , bit (252), 
bit (252)); 

call gener i c_math_$add_b i nary_compl ex (numl, num2, result); 

ARGUMENTS 

numl 

is a generic complex binary number. (Input) 
num2 

is a generic complex binary number. (Input) 
result 

is the generic complex binary value that is the result of adding numl and num2. 
(Output) 

Entry: generic math Ssubtract binary 

This entrypoint subtracts two generic binary numbers. 
USAGE 

declare gener i c_math_$subtract_b i nary entry (b i t (108) , bit (108), 
bit (108)); 

call gener i c_math_$subtract_b i nary (numl, num2, result); 

ARGUMENTS 

numl 

is a generic binary number. (Input) 
num2 

is a generic binary number. (Input) 
result 

is the generic binary value that is the result of subtracting num2 from numl. 
(Output) 
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Entry: generic math Ssubtract binary complex 

This entrypoint subtracts two generic complex binary numbers. 
USAGE 

declare gener i c_math_$subtract__b i nary_compl ex entry (b i t (252) , bit (252), 
bit (252)); 

call gener i c_math_$subtract_b i nary_compl ex (numl, num2, result); 

ARGUMENTS 

numl 

is a generic complex binary number. (Input) 
num2 

is a generic complex binary number. (Input) 
result 

is the generic complex binary value that is the result of subtracting num2 from 
numl. (Output) 



Entry: generic math Smultiply binary 

This entrypoint multiplies two generic binary numbers. 
USAGE 

declare gener i c_math_$mul t i pi y_b i nary entry (bi t (108) , bit(108), 
bit (108)); 

call gener i c_math_$mul ti pi y_bi nary (numl, num2, result); 

ARGUMENTS 

numl 

is a generic binary number. (Input) 
num2 

is a generic binary number. (Input) 
result 

is the generic binary value that is the result of multiplying numl by numl 
(Output) 
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Entry: generic math $multiply binary complex 

This entrypoint multiplies two generic complex binary numbers. 
USAGE 

declare gener ic_math_$mul t i pi y_b i nary_compl ex entry (b i t (252) , bit (252), 
bit (252)); 

call gener ic_math_$mul ti pi y_b i nary_comp lex (numl, num2, result); 

ARGUMENTS 

numl 

is a generic complex binary number. (Input) 
num2 

is a generic complex binary number. (Input) 
result 

is the generic complex binary value that is the result of multiplying numl by 
num2. (Output) 

Entry: generic math Sdivide binary 

This entrypoint divides two generic binary numbers. 
USAGE 

declare gener i c_math_$d ivi de_bi nary entry (b i t (108) , bit(108), bit(108)); 

call gener i c_math_$d i v i de_b i nary (numl, num2 , result); 

ARGUMENTS 

numl 

is a generic binary number. (Input) 
num2 

is a generic binary number. (Input) 
result 

is the generic binary value that is the result of dividing numl by num2. (Output) 
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Entry: generic math Sdivide binary complex 

This en try point divides two generic complex binary numbers. 
USAGE 

declare gener i c_math_$d i vi de_bi nary_compl ex entry (b i t (252) , bit (252), 
bit (252)); 

call gener ic_math_$di vi de_bi nary_comp lex (numl , num2, result); 

ARGUMENTS 

numl 

is a generic complex binary number. (Input) 
num2 

is a generic complex binary number. (Input) 
result 

is the generic complex binary value that is the result of dividing numl by num2. 
(Output) 



Name: get bound seg info 

The get_bound_seg_info_ subroutine is used by several object display programs 
concerned with bound segments to obtain information about a segment as a bound 
segment as well as general object information. 

USAGE 

declare get_bound_seg_i nf o_ entry (ptr, fixed bin (24), ptr, ptr, ptr, 
fixed bin (35)) ; 

call get_bound_seg_info_ (obj_ptr, b«t_count, oi_ptr, bm_ptr, sblk_ptr, 
code) ; 

ARGUMENTS 

obj_ptr 

is a pointer to the beginning of the segment. (Input) 
bit_count 

is the bit count of the segment. (Input) 
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oi_ptr 

is a pointer to the object format structure to be filled in by the object_info_$display 
entry point (see structure declaration in the description of the object_info_ 
subroutine). (Input) 



bm_ptr 

is a pointer to the bind map. (Output) 



sblk_ptr 

is a pointer to the base of the symbol block containing the bindmap. (Output) 



code 

is a standard status code. (Output) 



NOTES 



If obj_ptr points to an object segment but no bindmap is found, two possible codes 
are returned. One is error_table_$not_bound, indicating that the segment is not bound. 
The other is error_table_$oldobj, indicating that the segment was bound before the 
binder produced internal bind maps. If either one of these is returned, the structure 
pointed to by oi_ptr contains valid information. 



Name: get default wdir 

The get_default_wdir_ function returns the pathname of the user's current default 
working directory. 

USAGE 

declare get_def au 1 t_wd i r_ entry returns (char 068)); 
default_wdir = get_def aul t_wd i r_ () ; 
ARGUMENTS 
def aul t_ wdir 

is the pathname of the user's current default working directory. (Output) 
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Name: get definition 

The get_definition_ subroutine returns a pointer to a specified definition within an 
object segment. 

USAGE 

declare get definition entry (ptr, char (*) , char (*) , ptr, 
f ixed"bin(35)) ; 

call get_defi nit ion_ (def_section_ptr , segname, entryname, def_ptr, 
code) ; 

ARGUMENTS 

def_section_ptr 

is a pointer to the definition section of the object segment This pointer can be 

obtained via the object_info_ subroutine. (Input) 

segname 

is the name of the object segment (Input) 
entryname 

is the name of the desired entry point (Input) 
def_ptr 

is a pointer to the definition for the entry point (Output) 

code 

is a standard status code. If the entry point is found, code is 0. (Output) 



Name: get ec version 

The get_ec_version_ subroutine returns the version number of an exec_com, and the 
character position of the first character after the Aversion statement if any. 

USAGE 

del get ec version_ entry (char (*) , char (*) , fixed bin, fixed bin (21), 
fixed bin (35)) ; 

call get_ec_vers ion_ (dn, en, version, text_pos, code); 
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ARGUMENTS 
dn 

is the directory containing the exec_com. (Input) 

en 

is the name of the exec_com. (Input) 
version 

is the version number of the exec_com. (Output) 
text_pos 

is the character position of the first character following the Aversion statement, if 
any, or 1. (Output) 

code 

is a standard status code. (Output) 
ACCESS REQUIRED 

The user must have read access on the exec_com. 



Name: get entry arg descs 

This subroutine returns information about the calling sequence of a procedure entry 
| point Archive component pathnames are supported. 



Entry: get entry arg descs $get entry arg desc 

The get_entry_arg_descs_ entry point, given a pointer to the entry sequence or segdef 
of a procedure entry point, returns a list of argument descriptors describing the 
parameters of the entry point. 

USAGE 

declare get entry__arg descs entry (ptr, fixed bin, (*) ptr, 

f ixecfbin (35) ) ~ 

call get_entry_arg_descs_ (entry_ptr, nargs, desc_ptrs, code); 
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ARGUMENTS 
entry_ptr 

points to the entry sequence or segdef of the procedure entry point whose 
parameter descriptors are to be described. (Input) 

nargs 

is the number of parameters declared in the procedure entry point (Output) 
desc_ptrs 

is an array of pointers to the argument descriptors describing the declared 
parameters of the entry point If dimension (desc_ptrs, 1) is less than nargs, the 
pointers identify the first dimension (desc_ptrs, 1) parameter descriptors. (Output) 

code 

is a standard status code. It can be: 
error_table_$nodescr 

the entry point did not have parameter descriptors. (Output) 

NOTES 

For some version 0 object segments, a code of zero is returned, nargs is set, but the 
descriptor pointers in desc_ptrs are null. 



Entry: get entry arg descs Sinfo 

This entry point, given a pointer to the entry sequence or segdef of a procedure entry 
point, returns a list of argument descriptors describing the parameters of the entry 
point, plus a set of entry sequence flags which further describe the entry point 

USAGE 

declare get_entry_arg_descs__$ i nf o entry (ptr, fixed bin, (*) ptr, ptr, 
fixed bin(35)) ; 

call get_entry__arg_descs_$ i nf o (entry_ptr, nargs, desc_ptrs , 
entry_desc__i nfo_ptr , code); 

ARGUMENTS 

entry_ptr 

points to the entry sequence or segdef of the procedure entry point whose 
parameter descriptors are to be described. (Input) 

nargs 

is the number of parameters declared in the procedure entry point (Output) 
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desc_ptrs 

is an array of pointers to the argument descriptors describing the declared 
parameters of the entry point. If dimension (desc_ptrs, 1) is less than nargs, the 
pointers identify the first dimension (desc_ptrs, 1) parameter descriptors. (Output) 

entry_desc_inf o_ptr 

points to the entry_desc_info structure described under "Notes" below. (Input) 

code 

is a standard status code. It can be: 
error_table_$nodescr 

the entry point did not have parameter descriptors. (Output) 

NOTES 

The entry_desc_info_ptr argument of get_entry_arg_descs_$info points to the structure 
shown below. This structure is declared in entry_desc_info.incl.pll. 

del 1 entry_desc_i nfo aligned based (entry_desc_j nfo_ptr) , 

2 version fixed bin, 

2 flags, 

(3 basic_indicator , 

3 revision_l, 

3 has_descr iptors, 

3 variable, 

3 function) bit(l) unaligned, 

3 pad bit (13) unaligned, 

2 object__ptr ptr, 
2 bit_count fixed bin (2k); 

del entry_desc__i nfo_vers i on_2 fixed bin int static 

options (constant) init(2), 
entry_desc__i nf o_ptr ptr; 

STRUCTURE ELEMENTS 

version 

is the version number of this structure. The current version number is 2. The 
named constant, entry_desc_info_version_2, should be used to set this version 
number. 

flags 

are the flags which further describe the procedure entry point 
basic_indicator 

is on if the entry point is in a program written in the BASIC language. 

revision_l 

is on if the entry sequence has version i descriptor data. 
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has_descriptors 

is on if the entry sequence has argument descriptors describing its parameters, 
variable 

is on if the entry point accepts an undefined number of arguments, and has been 
declared with the options(variable) attribute. This flag will usually be off for 
entry points in command and active function procedures, even though these 
procedures accept a. variable number of arguments. Command and active function 
procedures usually do not declare their entry points with explicit parameters or 
with the options(variable) attribute. 

function 

is on if the procedure entry point is a function which returns a value. The final 
parameter argument descriptor describes this return value. 

object_ptr 

if the entry descriptor is being taken from an archive, this is the pointer to the 
base of the archive component Otherwise, this is null. (Output) 

bit_count 

if the entry descriptor is being taken from an archive, this is the bit count of 
the archive component. Otherwise, this is zero. (Output) 

entry _desc_inf o_version_2 

is a named constant which the caller should use to set the version number in the 
structure above. 

entry_desc_inf o_ptr 

points to the structure above. 



Entry: get entry_arg__descs__$text only 

This entry point, given a pointer to the entry sequence of a procedure entry point, 
returns a list of argument descriptors describing the parameters of the entry point. It 
differs from the get_entry_arg_descs_ entry point, in that it assumes that it is given a 
pointer to an entry sequence in the text section of the procedure, rather than checking 
to see if it was given a pointer to a segdef. 

USAGE 

declare get_entry_arg_descs_$text_on1y entry (ptr, fixed bin, (*) ptr, 
f ixed bin (35) ) » 

call get_entry_arg_descs_$text_onl y (entry_ptr, nargs, desc_ptrs, code); 
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ARGUMENTS 

The arguments are the same as for the get_entry_arg_descs_ entry point above. If 
entry_ptr does not point to an entry point in the text section, then 
error_table_$nodescr is returned as the value of code. 



Entry: get entry _arg^,descs___$text only info 

This entry point, given a pointer to the entry sequence of a procedure entry point, 
returns a list of argument descriptors describing the parameters of the entry point, 
plus a set of entry sequence flags which further describe the entry point It differs 
from the get_entry_arg_descs_$info entry point, in that it assumes that it is given a 
pointer to an entry sequence in the text section of the procedure, rather than checking 
to see if it was given a pointer to a segdef. 

USAGE 

declare get_entry__arg_descs_$text_only_i nf o entry (ptr, fixed bin, (*) 
ptr, ptr, fixed bin (35)); 

call get_entry_arg_descs_$text_only_info (entry__ptr, nargs, desc_ptrs, 
entry_desc_i nf o_ptr , code); 

ARGUMENTS 

The arguments are the same as for the get_entry_arg_descs_$info entry point above. 



Name: get entry name 

The get_entry_name_ subroutine, given a pointer to an externally defined location or 
entry point in a segment, returns the associated name. 

USAGE 

declare get_entry_name_ entry (ptr, char (*) , fixed bin(l8), char (8) 
aligned, fixed bin (35)); 

call get_entry_name_ (entry_ptr, symbolname, segno, lang, code); 
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ARGUMENTS 
entry_ptr 

is a pointer to a procedure entry point (Input) 
symbolname 

is the name corresponding to the location specified by entry_ptr. The maximum 
length is 256 characters. (Output) 

segno 

is the segment number of the object segment where symbolname is found. It is 
useful when entry_ptr does not point to a text section. (Output) 

lang 

is the language in which the segment or component pointed to by entry_ptr was 
compiled. (Output) 

code 

is a standard status code. (Output) 



Name: get entry point del 

The get_entry_point_dcl_ subroutine returns attributes needed to construct a PL/ 1 
declare statement for external procedure entry points and for error_table_ codes and 
other system— wide external data. The program obtains the attributes from data files 
declaring all unusual procedure entry points (e.g., ALM segments), and system-wide 
data values (e.g., sys_info$max_seg_size), and from the argument descriptors describing 
the entry point's parameters that are included with the entry point itself. 

The get_entry_point_dcl_ entry point returns the declaration for an external value, 
either from one of the data files, or by using the parameter argument descriptors 
associated with the procedure entry point. It makes a special case of error_table_ 
values by always returning 'fixed bin(35) ext static' for them. For example, given the 
name iox_$put_chars, it might return: 

entry (ptr, ptr, fixed bi n (21) » fixed bin(35)) 

Note that neither the name of the external value nor any trailing semicolon (;) is 
returned as part of the declaration. 

Archive component pathnames are supported. 
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USAGE 

del get_entry_point_dcl_ entry (char (*) , fixed bin, fixed bin, 
char (*) varying, char (32) varying, f i xed b i n (35) ) ; 

call get_entry_point_dcl_ (name, dd_style, line_length, del, type, 
code) ; 

ARGUMENTS 

name 

is the name of the external entry point or data item whose declaration must be 
obtained. (Input) 

dcl_style 

is the style of indentation to be performed for the name. See "Notes" below for 
a list of allowed values. (Input) 

linejength 

is the maximum length to which lines in return value are allowed to grow when 
indentation is performed. (Input) 

del 

is the declaration that was obtained. (Output) 

type 

is the type of declaration. In the current implementation, this is always a null 
string. (Output) 

code 

is a standard status code describing any failure to obtain the declaration. (Output) 
NOTES 

Three styles of declaration indentation are supported by the dcl_style argument 
described above. Style 0 (dcl_style = 0) involves no indentation. The declaration is 
returned as a single line. 

Style 1 (dcl_style = 1) indents the declaration in the format similar to the indent 
command. Long declarations are broken into several lines. For example, a declare 
statement for hcs_$initiate_count would appear as: 

del hcs_$ i ni tiate_count entry (char (*) , char (*) , char (*) , 
fixed bin (2*0, fixed bin (2), ptr, fixed bin (35)); 

when the string "del hcs_$initiate_count" is concatenated with the value returned by 
get_entry_point_dcl_, and a semicolon (;) is appended to this value. 
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Style 2 (dcl_style = 2) indents the declaration in an alternate format that makes the 
name of the entry point stand out from its declaration. It assumes that the name of 
the entry point begins in column 11 (indented one horizontal tab stop from left 
margin), and the declaration begins in column 41. In style 2, the declare statement for 
hcs_$initiate_count would appear as: 

del hcs_$ini tiate__count entry (char (*) , (char (*) , (char (*) , 

fixed bin (24), fixed bin (2), 
ptr, fixed bin (35)) ; 

Most command and active function entry points do not declare arguments in their 
procedure statements since they accept a variable number of arguments. Neither do 
they use the options( variable) attribute in their procedure statements. Therefore, when 
get_entry_point_dcl_ encounters a procedure entry point with no declared arguments 
and without options(variable), it assumes the options( variable) attribute required for 
commands and active functions and returns: 

entry options (var i able) 
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It distinguishes between such assumed options(variable) entries and those that explicitly 
use the options( variable) attribute in their procedure statement by returning "entry" for 
the assumed case and "entryO" for the explicit case. Thus, for the display_entry_point_dcl 
command, which explicitly uses options(variable) in its procedure statement, 
get_entry_point_dcl_ returns: 

entry () opt i ons (var i abl e) 

For procedures which use structures as arguments, certain structure declarations are 
inexactly returned as parameter declarations because the mechanism for encoding 
argument descriptors does not provide an adequate description of the alignment of a 
structure. The descriptor only determines whether the overall structure is packed or 
not, and does not specify whether or not it was originally declared with the aligned 
attribute. 

The following structures generate the same argument descriptors, even though PL/ 1 
treats the level 1 structures as having different attributes: 

del 1 s2 structure aligned, 

2 ell fixed bin aligned, 
2 el 2 fixed bin aligned; 

del 1 s2 structure, 

2 ell fixed bin aligned, 
2 el 2 fixed bin aligned; 

get_entry_point_dcl_ reproduces the declaration for s2 when either si or s2 are used 

as parameters for an entry point. In order to bypass this problem, declare the 

subroutine properly in your personal .del segment (see "User-Provided Data Files" 
below), and place this segment in your "declare" search paths. 

SEARCH LIST 

The get_entry_point_dcl_ subroutine uses the "declare" search list, which has the 
synonym "del", to find data files describing unusual procedure entry points. For more 
information about search lists, see the descriptions of the search facility commands 
and, in particular, the add_search_paths command description. Type: 

! pr i nt_search_paths declare 

to see what the current declare search list is. The default search list identifies the 
data file: 

>sss>pl 1 .del 
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USER-PROVIDED DATA FILES 

Users may provide data files that redeclare standard system entry points (e.g., 
redeclaring a subroutine as a function), or that declare their own entry points or 
external data items. The add_search_paths command can be used to place user-provided 
data files in the "declare" search list For example: 

! add_search_paths declare [hd]>my_pl 1 .del -first 

Declarations have the general form of: 

vi rtual_entry declaration 

For example: 

ioa_ entry opt i ons (var i abl e) 

Note that the word "del" is not included in the data item, nor does the declaration 
end with a semicolon (;). External data values are declared in a similar fashion. For 
example: 

i ox_$user_output ptr external static 



Name: get equal name 

The get_equal_name_ subroutine accepts an entryname and an equal name as its input 
and constructs a target name by substituting components or characters from the 
entryname into the equal name, according to the Multics equal convention. Refer to 
"Constructing and Interpreting Names" in the Programmer's Reference Manual for a 
description of the equal convention and for the rules used to construct and interpret 
equal names. 

USAGE 

declare get_equal_name_ entry (char (*) , char (*) , char (32) , 
fixed bin (35)) ; 

call get_equal_name_ (entryname, equal_name, target_name, code); 
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ARGUMENTS 
entryname 

is the entryname from which the target is to be constructed. Trailing blanks in 
the entryname character string are ignored. (Input) 

equal_name 

is the equal name from which the target is to be constructed. Trailing blanks in 
the equal name character string are ignored. (Input) 

target_name 

is the target name that is constructed. (Output) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$bad_equal_name 

the equal name has a bad format 
error_table_$badequal 

there is no letter or component in the entryname that corresponds to a 

percent character (%) or an equal sign (=) in the equal name. 
error_table_$longeql 

the target name to be constructed is longer than 32 characters. 

NOTES 

If the error_table_$badequal status code is returned, then a target_name is returned in 
which null character strings are used to represent the missing letter or component of 

entryname. 

If the error_table_$longeql status code is returned, then the first 32 characters of the 
target name to be constructed are returned as target_name. 

The entryname argument that is passed to get_equal_name_ can also be used as the 
target_name argument, as long as the argument has a length of 32 characters. 



Entry: get equal name Scomponent 

This entry point accepts an archive and component name and two equal names as 
input and constructs a target archive and component name by substituting components 
or characters from the archive and component names into the equal names, according 
to the Multics archive component pathname equal convention. Refer to the 
Programmer's Reference Manual for a description of archive component pathnames and 
the equal convention. 



2-363 



AG93-05 



get_equal_name_ 



get_equal_name_ 



USAGE 

declare get_equal_name_$component entry (char (*) , char (*) , char (*) , 
char(*), char (32), char (32) , f i xed b i n (35) ) ; 

call get_equal_name_$component (entryname, component, equal_entryname, 
equal _component, target_entryname, target_component , code) ; 

ARGUMENTS 

entryname 

is the archive name from which the target archive name is constructed, or is the 
entryname from which the target component name is constructed if the source 
pathname is not an archive component pathname. (Input) 

component 

is the component name from which the target component name is constructed or 
is a null string if the source pathname is not an archive component pathname. 
(Input) 

equal_entryname 

is the equal name from which the target archive name is constructed or is the 
equal name from which the target entryname is constructed if the target pathname 
is not an archive component pathname. (Input) 

equal_component 

is the equal name from which the target component name is constructed or is a 
null string if the target pathname is not an archive component pathname. (Input) 

target_entryname 

is the target archive name that is constructed or is the target entryname that is 
constructed if the target pathname is not an archive component pathname. 
(Output) 

target_component 

is the target component name that is constructed or is a null string if the target 
pathname is not an archive component pathname. (Output) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$bad_equal_name 

either equal_entryname or equal_component has a bad format. 
error_table_$badequal 

there is no letter or component in the archive or component name that 

corresponds to a percent character (%) or an equal sign (=) in the appropriate 

equal name. 
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error_table_$longeql 

the target archive or component name to be constructed is longer than 32 
characters. 
error_table_$no_archive_f or_equal 

the target pathname has an equal name in the archive name position but the 
source pathname is not an archive component pathname. 

NOTES 

If the error_table_$badequal status code is returned, the name returned in the 
appropriate output argument is constructed using null character strings to represent the 
letters or component names missing from the source name. 

If the error_table_$longeql status code is returned, the first 32 characters of the 
constructed name are returned in the appropriate output argument. 

The two pairs of input arguments to this subroutine are expected to be the output 
arguments from two calls to expand_pathname_$component, one call for the source 
pathname and one for the pathname containing the equal names. 

The output arguments of this subroutine should be used in a call to the 
initiate_file_$component subroutine. For example: 

call expand_pathname_$ component (argl, source__dir, source_ename, 

source__comp, code) ; 
i f code ~= 0 then . . . 

call £xpand_patnname_$ component (arg2, target_dir, equal_entry, 

equal _component, code) ; 
i f code ~= 0 then . . . 

call get_equal_name_$component (source_ename, source_comp, equal_entry, 

equal _component, target_ename, target_comp, code) ; 
i f code ~= 0 then . . . 

call i n i t i ate_f i 1 e_$ component (source_dir, source_ename, source_comp, 

R_ACCESS, source_ptr, source_b i t_count , code); 
i f code ~= 0 then . . . 

call i ni t iate_f i 1 e_$component (target_dir, target_ename, target_comp, 

R_ACCESS, target_ptr, target_bi t_count , code); 
i f code ~= 0 then , , « 
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Name: get__external_ variable 

The get_external_variable_ subroutine obtains the location and size of an external 
variable. 

USAGE 

declare get_externai_var i abie_ entry (char (*) , ptr, fixed b i n (1 S) » ptr, 
fixed bin (35)) 5 

call get_external_var i able_ (vname, vptr, vsize, vdesc_ptr, code); 

ARGUMENTS 

vname 

is the name of the external variable. (Input) 

vptr 

is a pointer to the current allocation of the external variable. (Output) 

vsize 

is the size (in words) of the external variable. (Output) 
vdesc_ptr 

is a pointer to a standard argument descriptor array describing the external 
variable. If the external variable does not have descriptor information associated 
with it, a null pointer is returned. (Output) 

code 

is a standard status code. (Output) 



Name: get group id 

The get_group_id_ function returns the 32-character access identifier of the process in 
which it is called. The access identifier is of the form: 

Person_id.Project_id. tag 
USAGE 

declare get_group_i d_ entry returns (char (32) ) ; 
user_id = get = group = i d_ () ; 
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ARGUMENTS 
user_id 

contains the access identifier that is returned to the user. (Output) It is a 
left-justified character string, padded with trailing blanks. 

Entry: get group id $tag_star 

This entry point returns the access identifier of its caller with the instance component 
replaced by an asterisk (*). 

USAGE 

declare get_group_i d_$ tag_star entry returns (char (32)); 

user_id = get_group_i d_$tag_star () ; 

ARGUMENTS 

user_id 

contains the access identifier that is returned to the user. (Output) It is a 
lef trustified character string, padded with trailing blanks. 



Name: get initial ring 

The get_initial_ring_ subroutine returns the current value of the ring number in which 
the process was initialized. 

USAGE 

declare get_i ni t i al_r i ng_ entry (fixed bin(3)); 

call get_ini tial_r i ng_ (i_ring); 

ARGUMENTS 

Lring 

is the initial ring for the process. (Output) 
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Name: get line length 

The get_line_length_ function returns the line length currently in effect on a given 
I/O switch. If the line length is not available (for any reason), a status code is 
returned, and a default line length is returned. 



Entry: get line length $stream 

This entry point returns the line length of a given I/O switch, identified by name. 
USAGE 

declare get_l i ne_l ength_$stream entry (char (*) , fixed bin (35)) returns 
(f i xed bin); 

line_length = get_l i ne_l ength_$stream (swi tch_name, code); 

ARGUMENTS 

switch_name 

is the name of the switch whose line length is desired. (Input) If switch_name is 
null, the user_output I/O switch is assumed. 

code 

is a standard status code. (Output) 
line_length 

is the line length of switch_name. (Output) 



Entry: get line length Sswiteh 

This entry point returns the line length of a given I/O switch, identified by pointer. 
USAGE 

declare get_l i ne_l ength_$swi tch entry (ptr, fixed bin(35)) returns 
(f i xed bin); 

line__length = get__l i ne_l ength_$swi tch (switch_ptr, code); 

ARGUMENTS 

switch_ptr 

is a pointer to the I/O control block of the switch whose line length is desired, 
(Input) If switch_ptr is null, the user_output I/O switch is assumed. 

code 

is a standard status code. (Output) 
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linejength 

is the line length of switch_name. (Output) 



Name: get__lock id 

The get_lock„id = subroutine returns the 36-bit unique lock identifier to be used by a 
process in setting locks. By using this lock identifier, a convention can be established 
so that a process wishing to lock a data base and finding it already locked can verify 
that the lock is set by an existing process. 

USAGE 

declare get_lock_id__ entry (bit (36) aligned); 

call get_lock_id_ (lock_id) ; 

ARGUMENTS 

lock_id 

is the unique identifier of this process used in locking. (Output) 
NOTES 

For a more detailed discussion of locking see the set_lock_ subroutine description. 



Name: get_pdir 

The get_pdir_ function returns the absolute pathname of the user's process directory. 
For a discussion of process directories, see the Programmer's Reference Manual. 

USAGE 

declare get_pdir_ entry returns (char(l68)); 

processed ir * get_pdir_ (); 

ARGUMENTS 

process_dir 

contains the absolute pathname of the user's process directory. (Output) It is 
assigned a left-justified character string, padded with trailing blanks. 
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Name: get privileges 

The get_privileges_ function returns the access privileges of the process. (See "Access 
Control" in the Programmer's Reference Manual for more information on access 
privileges.) 

USAGE 

declare get_pr i vi 1 eges_ entry returns (bit (36) aligned); 

pr ivi lege_str i ng - get_pr i vi 1 eges_ () ; 

ARGUMENTS 

privilege_string 

is a bit string with a bit set OT'b) for each access privilege the process has. 
(Output) 

NOTES 

The individual bits in privilege_string are defined by the following PL/ 1 structure: 

del 1 privileges unaligned, 

2 ipc b i t (1 

2 dir bit(l 

2 seg bit(l 

2 soos bit(l 

2 ringl bit(l 

2 rep bit (I! 

2 mbz bit (30) ; 

STRUCTURE ELEMENTS 

ipc 

indicates whether the access isolation mechanism (AIM) restrictions for 
sending/receiving wakeups to/from any other process are bypassed for the calling 
process. 
"l"b yes 
"0"b no 

dir 

indicates whether the AIM restrictions for accessing any directory are bypassed for 
the calling process. 
'T'b yes 
"0"b no 



11/86 



2-370 



AG93-05A 



get_privileges_ 



get_process_access_class_ 



seg 

indicates whether the AIM restrictions for accessing any segment are bypassed for 
the calling process. 
"l"b yes 
"0"b no 

soos 

indicates whether the AIM restrictions for accessing directories that have been set 
security-out-of -service are bypassed for the calling process. 
'T'b yes 
"(Tb no 

ringl 

indicates whether the AIM restrictions for accessing any ring 1 system segment are 
bypassed for the calling process. 
"l"b yes 
"0"b no 

rep 

indicates whether the AIM restrictions for accessing resources through RCP 
resource management are bypassed for the calling process. 
"l"b yes 
"0"b no 

mbz 

is unused and is "0"b. 



Name: get process access class 

The get_process_access_class_ function returns the AIM access class contained in the 
current process authorization. 

USAGE 

declare get_process_access_class_ entry returns (bit (72) aligned); 

access_class ■ get_process_access_c 1 ass_ () ; 

ARGUMENTS 

access_class 

is the access class derived from the process login authorization. (Output) 
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Name: get process authorization 

The get_process_authorization_ function returns the process' current authorization. This 
includes the login authorization and any privileges that have been enabled. 

USAGE 

declare get_process_author i zat i on_ entry returns (b 1 1 (72) aligned); 

authorization = get_process_author i zation__ (); 

ARGUMENTS 

authorization 

is is the current process authorization, including privileges. (Output) 



Name: get process id 

The get_process_id_ function returns the 36-bit identifier of the process in which it is 
called. The identifier is generated by the system when the process is created. 

USAGE 

declare get_process_i d_ entry returns (bit (36)); 

proc_id ■ get_process_id_ () ; 

ARGUMENTS 

proc_id 

contains the 36-bit identifier of the process. (Output) 



Name: get process__max_authorization 

The get__process_max_authorization_ function returns the maximum AIM authorization 
of the process. See the Programmer's Reference Manual for additional information on 
AIM. 

USAGE 

declare get_process_max_author i zat i on_ entry returns (b s t (72) aligned); 
max_author i zat i on ■ get_process_max_author i zat i on_ () ; 



11/86 



2-372 



AG93-05A 



get_process_max_authorization_ 



get_shortest_path. 



ARGUMENTS 

max_authorization 

is the returned maximum authorization. (Output) 



Name: get ring__ 

The get_ring_ function returns to the caller the number of the protection ring in 
which the caller is executing. For a discussion of rings see "Intraprocess Access 
Control" in the Programmer's Reference Manual. 

USAGE 

declare get_ring_ entry returns (fixed bin(3)); 

r i ng_no = get_r i ng_ () ; 

ARGUMENTS 

ring_no 

is the number of the ring in which the caller is executing. (Output) 



Name: get shortest path 

Shortens the specified pathname by replacing each directory level with the shortest 
name on the directory. If the caller does not have access to get the names of a 
directory, the original name of that directory is left intact 

USAGE 

del get_shortest_path_ entry (char (*)) returns (char (168)); 
short__path = get_shortest_path_ (or igi nal_path) ; 
ARGUMENTS 
original_path 

is the pathname of a storage system entry. (Input) 
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NOTES 

When more than one name qualify as the shortest name for a directory, an attempt is 
made to select the name containing all lower case characters. If more than one name 
still qualifies, these names are compared to the primary name of the directory. The 
first name found with the same first character as the primary name is chosen. This 
comparison is case independent. 



Name: get system aim attributes 

This subroutine returns a structure describing the AIM attributes defined on this 
system. 

USAGE 

declare get_system_aim_attr i butes_ entry (ptr, char (8) , ptr, 
fixed bin (35)) ; 

call get_system_aim_attr ibutes_ (area__ptr, vers i on_wan ted, 
aim_attr ibutes_ptr, code); 

ARGUMENTS 

area_ptr 

is a pointer to an area in which the aim_attributes structure is allocated. (Input) 
version_wanted 

is the version of the structure that the caller expects get_system_aim_attributes_ to 
return. The only supported version at present is given by the value of the named 
constant AIM_ATTRIBUTES_VERSI0N_1 defined in the system include file 
aim_attributes.incl.pll. (Input) 

aim_attributes_ptr 

is set to locate the aim_attributes structure allocated by this program. (Output) 

code 

is a standard system status code. (Output) It can be one of the following: 
0 

the aim_attributes structure was successfully allocated. 
error_table_$unimplemented__version 

the version of the structure requested by the caller is not implemented by 

get_system_aim_attributes_. 
error_table_$noalloc 

there was not sufficient room in the caller's area to allocate the aim_attributes 
structure. 
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NOTES 



The aim_attributes structure is defined in the system include file aim_attributes.incl.pll 
and has the following format: 



del 1 aim attributes 



al i gned based, 
char (8) unal i gned, 
bit (72) , 



2 version 



2 access_class_cei 1 ing 



2 levels (0:7), 



3 long__name 
3 short_name 



char (32) unaligned, 
char (8) unal i gned, 



2 categor i es (18) , 



3 long_name 
3 short_name 



char (32) unal i gned, 
char (8) unal i gned, 



STRUCTURE ELEMENTS 
version 

is the version of this structure (currently AIM_ATTRIBUTES_VERSION_l). 
access_class_ceiling 

is the maximum authorization or access class in terms of the AIM attributes, 
levels 

are the sensitivity levels defined on this system. Only the entries from levels(O) 
through levels(highest_level) contain definitions. The remaining entries are all 
blank. 

long_name 

is the long name of this sensitivity level. 

short_name 

is the short name of this sensitivity level. 

categories 

are the access categories defined on this system. Only the first n_categories 

entries of this substructure contain definitions. The remaining entries are all 
blank. 

long_name 

is the long name of this sensitivity level. 

short_name 

is the short name of this sensitivity level. 
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Name: get system free area 

The get_system_free_area_ function returns a pointer to the system free area for the 
ring in which it was called. Allocations by system programs are performed in this 
area. 

USAGE 

declare get_system_f ree_area__ entry returns (ptr) ; 
area_ptr = get__system_f ree_area_ () ; 
ARGUMENTS 
area_ptr 

is a pointer to the system free area. (Output) 



Name: get temp segment 

The get_temp_segment_ subroutine acquires a temporary segment in the process 
directory. The segment returned to the caller is zero-length. 

A free pool of temporary segments is associated with each user process. The pool 
concept makes it possible to use the same temporary segment more than once during 
the life of a process. Reusing temporary segments in this way avoids the cost of 
creating a segment each time one is needed. 

If more than one temporary segment is required, use the get_temp_segments_ 
subroutine. 

USAGE 

declare get_temp_segment__ entry (char (*) , ptr, fixed bin (35)): 
| call get_temp_segment_ (program, temp_seg_ptr , code); 
ARGUMENTS 
program 

is a 32-character field identifying the program on whose behalf the temporary 
segment is to be used. This field is displayed by the list_temp_segments 
command. Besides giving the name of the command or subroutine invoked by the 
user, it can also briefly describe how the temporary segment is used; for example, 
"sort_seg (sort indexes)". (Input) 

temp_seg_ptr 

is a returned pointer to the requested temporary segment. (Output) 
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code 

is a standard status code. (Output) 
NOTES 

This subroutine assigns a temporary segment to its caller. It creates a new temporary 
segment and adds it to the free pool if one is not currently available to satisfy the 
request. The temporary segment is created in the process directory with a unique 
name including the temp.NNNN suffix, where NNNN is the segment number of the | 
segment in octal. See the description of the release_temp_segment_ or the 
release_temp_segments_ subroutine for a description of how to return a temporary 
segment to the free pool. 

The list_temp_segments command can be used to list the temporary segments being 
used by a process. 



Name: get temp segments 

The get_temp_segments_ subroutine puts temporary segments in the process directory 
for whatever purpose the caller may have. The segments returned to the caller are 
zero-length. 

A free pool of temporary segments is associated with each user process. The pool 
concept makes it possible to use the same temporary segment more than once during 
the life of a process. Reusing temporary segments in this way avoids the cost of 
creating a segment each time one is needed. 

USAGE 

declare get_temp_segments_ entry (char (*) , (*) ptr, fixed bin (35)); 

call get_temp_segments_ (program, ptrs, code); 

ARGUMENTS 

program 

is a 32-character field identifying the program on whose behalf the temporary 
segment is to be used. This field is displayed by the list_temp_segments 
command. Besides giving the name of the command or subroutine invoked by the 
user, it can also briefly describe how the temporary segment is used; for example, 
"sort_seg (sort indexes)". (Input) 

ptrs 

is an array of returned pointers to the requested temporary segments. (Output) 

code 

is a standard status code. (Output) 



11/86 



2-377 



AG93-05A 



get_temp_segments_ 



get_wdir_ 



NOTES 

This subroutine assigns temporary segments to its caller. It creates new temporary 
segments and adds them to the free pool if there currently are not enough available 
to satisfy the request. The temporary segments are created in the process directory 
with a unique name including the temp.NNNN suffix, where NNNN is the segment 
number of the segment in octal. See the description of the release_temp_segments_ or 
the release_temp_segment_ subroutine for a description of how to return temporary 
segments to the free pool. 

The number of segments returned to the caller is determined by the bounds of the 
ptrs array above. 

The list_temp_segments command (described in the the Commands manual) can be used 
to list the temporary segments being used by a process. 



Name: get wdir 

The get_wdir_ function returns the absolute pathname of the user's current working 

directory. For a discussion of working directories, see "System Directories" in the 
Programmer's Reference Manual. 

USAGE 

declare get_wdir_ entry returns (char(l68)); 

declare working_dir character (168); 

working_dir = get_wd i r_ () ; 

ARGUMENTS 

working_dir 

contains the absolute pathname of the user's current working directory. (Output) 
NOTES 

Working directories are per-ring. If get_wdir_ is invoked in a ring for which a 
working directory has never been set, it will use the sub_err_ mechanism to signal an 
error (see the sub_err_ subroutine). The sub_err_ action code given is 
"ACTION_CANT_RESTART". The status code is error_table_$no_wdir. See the 
Programmer's Reference Manual for more information on ring protection. 
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Name: hash„ 

The hash_ subroutine is used to maintain a hash table. It contains entry points that 
initialize a hash table and insert, delete, and search for entries in the table. 

A hash table is used to locate entries in another data table when the length of the 
data table or the frequency with which its entries are referenced makes linear 
searching uneconomical. ■ 

A hash table entry contains a name and a value. The name is a character string (of 
up to 32 characters) that is associated in some way with a data table entry. The value 
is a fixed binary number that can be used to locate that data table entry (for 
example, an array index or an offset within a segment). The entries in the hash table 
are arranged so that the location of any entry can be computed by applying a hash 
function to the corresponding name. 

It is possible for several names to hash to the same location. When this occurs, a 
linear search from the hash location to the first free entry is required, to find a 
place for a new entry (if adding), or to find out whether an entry corresponding to 
the name exists (if searching). The more densely packed the hash table, the more 
likely this occurrence is. To maintain a balance between efficiency and table size, 
hash_ keeps a hash table approximately 75 percent full, by rehashing it (i.e. rebuilding 
it in a larger space) when it becomes too full. 

The number of entries is limited only by the available space. The table uses eight 
words per entry plus ten words for a header. If an entire segment is available to 
hold the table, it can have over 32,000 entries. 



Entry: hash_$in 

This entry point adds an entry to a hash table. If the additional entry makes the 
table too full, the table is rehashed before the new entry is added (see the description 
of the rehash_ subroutine). 

USAGE 

declare hash_$in entry (ptr, char (*) , bit (36) aligned, fixed b i n (35) ) • 

call hash_$in (table_ptr, name, value, code); 

ARGUMENTS 

table_ptr 

is a pointer to the hash table. (Input) 
name 

is a name associated with a data table entry. It can be up to 32 characters long. 
(Input) 
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value 

is the locator (e.g., index or offset) of the data table entry associated with name. 
(Input) 

code 

is a standard system error code with the following values: (Output) 
0 

entry added successfully. 
error_table_$segnamedup 

entry already exists, with same value. 
error_table_$namedup 

entry already exists, with different values. 
error_table_$full_hashtbl 

hash table is full and there is no room to rehash it into a larger space. 



Entry: hash_$inagain 

This entry point adds an entry to a hash table. It is identical to the hash_$in entry 
except that it never tries to rehash the table. The new entry is added unless the table 
is completely full. This entry point is used by the rehash_ subroutine to avoid loops. 
It can also be used by an application that has a hash table embedded in a larger data 
base, where automatic rehashing would damage the data base. 

USAGE 

declare hash_$ i naga i n entry (ptr, char (*) , bit (36) aligned-, fixed 
bin (35)) ; 

call hash_$ i naga i n (table_ptr, name, value, code); 

ARGUMENTS 

table_ptr 

is a pointer to the hash table. (Input) 
name 

is a name associated with a data table entry. It can be up to 32 characters long. 
(Input) 

value 

is the locator (e.g., index or offset) of the data table entry associated with name. 
(Input) 

code 

is a standard system error code with the following values: (Output) 
0 

entry added successfully. 
error_table_$segnamedup 

entry already exists, with same value. 
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error_table_$namedup 

entry already exists, with different values. 
error_table_$full_hashtbl 

hash table is full and there is no room to rehash it into a larger space. 



Entry: hash_$make 



This entry point initializes an empty hash table. The caller must provide a segment to 
hold it, and must specify its initial size (see hash_$opt_size). 

USAGE 

declare hash_$make entry (ptr, fixed bin, fixed bin(35))» 

call hash_$make (table_ptr, size, code); 

ARGUMENTS 

table_ptr 

is a pointer to the table to be initialized. (Input) 

size 

is the initial number of entries. (Input). It is recommended that the value 
returned by hash_$opt_size be used. 

code 

is a standard status code. (Output). It can be: 
0 

if there is no error. 
error_table_$invalid_elsize 
if size is too large. 



Entry: hash_$opt size 

This entry point, given the number of entries to be placed in a new hash table 
initially, returns the optimal size for the new table. This function is used when 
rehashing a full hash table, and should be used when making a new hash table. 

USAGE 

declare hash_$opt_s i ze entry- (fixed bin) returns (fixed bin); 
s i ze=hash__$opt__s i ze (n_entr i es) ; 
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ARGUMENTS 
n_entries 

is the number of entries to be added. (Input) 

size 

is the optimal table size for that number of entries. (Output) 



Entry: hash $out 

This entry point deletes a name from the hash table. 
USAGE 

declare hash_$out entry (ptr, char (*) , bit (36) aligned, fixed bin (35)) 5 

call hash_$out (table_ptr, name, value, code); 

ARGUMENTS 

table_ptr 

is a pointer to the hash table. (Input) 
name 

is the name to be deleted. (Input). Its maximum length is 32 characters, 
value . 

is the locator value corresponding to name. (Input) 

code 

is a standard status code. (Output). It can be; 
0 

name was found and deleted. 
error_table_$noentry 

name was not found in the hash table. 



Entry: hash_$search 

This entry point searches a hash table for a given name and returns the corresponding 
locator value. 

USAGE 

declare hash_$search entry (ptr, char (*) , bit (36) aligned, fixed 
bin (35)) ; 

call hash_$search (table_ptr, name, value, code); 
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ARGUMENTS 
table_ptr 

is a pointer to the hash table. (Input) 
name 

is the name to be searched for. (Input). It can be up to 32 characters long, 
value 

is the locator value corresponding to name. (Output) 

code 

is a standard status code. (Output). It can be: 
0 

name was found. 
error_table_$noentry 

name was not found in the hash table. 



Name: hash index__ 

The hash_index_ subroutine returns the value of a hash function of a character string. 
USAGE 

declare hash_index_ entry (ptr. fixed b i n (2 1 ) . fixed bin, fixed bin) 
returns (fixed bin); 

hash_value - hash_index_ (string_ptr, string_len, mbz, table_size) ; 

ARGUMENTS 

string_ptr 

is a pointer to the character string to be hashed. This character string must be 
aligned. (Input) 

string_len 

is the length of the character string. (Input) 

mbz 

is reserved and must be zero. (Input) 
table_size 

is the number of entries in the hash table. (Input) 
NOTES 

The value returned is between zero and table_size-l, inclusive. 
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Name: hcs $add acl entries 

This entry point adds specified access modes to the access control list (ACL) of the 
specified segment If an access name already appears on the ACL of the segment, its 
mode is changed to the one specified by the call. 

USAGE 

declare hcs_$add_acl_entr i es entry (char (*) , char (*) , ptr, fixed bin, 
fixed bin (35)) ; 

call hcs_$add_acl_entr ies (dir_name, entryname, acl_ptr, acl_count, 
code) ; 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment (Input) 
acl_ptr 

points to a user-filled segment_acl_array structure (see "Entry Information" below). 
(Input) 

acl_count 

contains the number of ACL entries in the segment_acl_array structure (see "Entry 
Information" below). (Input) 

code 

is a storage system status code. (Output) 
ENTRY INFORMATION 

The segment_acl_array structure should be declared in the following way: 

del 1 segment_acl_array (acl_count) aligned like segment_acl_entry ; 

The segment_acl_entry structure (declared in the include file acl_structures.incl.pll) is 
as follows: 

del 1 segment_ac l_entry aligned based, 

2 access_name char (32) unaligned, 

2 mode bit (36) aligned, 

2 extended_mode bit (36) aligned, 

2 status_code fixed bin(35); 

STRUCTURE ELEMENTS ) 

access_name 

is the access name (in the form Person_id.Project_id.tag) that identifies the 
processes to which this ACL entry applies. 

mode 

contains the modes for this access name. The first three bits correspond to the 
modes read, execute, and write. The remaining bits must be zeros. For example, 
rw access is expressed as "101"b. The include file access_mode_values.incl.pll 
defines mnemonics for these values: 
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del (N_ACCESS init ("000"b) , 

R_ACCESS init ( ,, 100"b) , 

E_ACCESS init ("010"b) , 

W_ACCESS init ("001"b) , 

RE_ACCESS init ("1 10"b) , 

REW_ACCESS init ("lll"b) , 

RW_ACCESS init ( M 101"b) ) , 
bit (3) internal static options (constant); 



extended_mode 

should contain the value "0"b. (This field is for use with extended access and 
should only be used in subsystems defining extended access modes). 

status_code 

is a storage system status code for this ACL entry only. 
NOTES 

If code is returned as error_table_$argerr, then the erroneous ACL entries in the 
segment_acl structure have status_code set to an appropriate error code. No processing 
is performed. 

If the segment is a gate and if the validation level is greater than ring 1, then access 
is given only to names that contain the same project as the user or to the SysDaemon 
project. If the ACL to be added is in error, no processing is performed and the 
subroutine returns the code error_table_$invalid_project_for_gate. 



Name: hes $add dir acl entries 

This entry point adds specified directory access modes to the access control list (ACL) 
of the specified directory. If an access name already appears on the ACL of the 
directory, its mode is changed to the one specified by the call. 

USAGE 

declare hcs_$add_d i r_ac l_entr i es entry (char (*) , char (*) , ptr , 
fixed bin, fixed bin (35)); 

call hcs_$add_d i r_acl_entr ies (dir_name, entryname, acl_ptr, acl__count, 
code) ; 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
acl_ptr 

points to a user-filled dir_acl_array structure (see "Entry Information" below). 
(Input) 

acl_count 

contains the number of ACL entries in the dir_acl_array structure (see "Entry 
Information" below). (Input) 

code 

is a storage system status code. (Output) 
ENTRY INFORMATION 

The dir_acl_array structure should be declared in the following way: 
del 1 d i r_ac l_array (acl_count) aligned like di r_acl_entry; 

The dir_acl_entry structure (declared in the include file acl_structures.incl.pll) is as 
follows: 

del 1 d i r_acl_entry based, 

2 access_name char (32) unaligned, 

2 mode bit (36) aligned, 

2 status_code fixed bin(35); 

STRUCTURE ELEMENTS 

access_name 

is the access name (in the form Person_id.Project_id.tag) that identifies the 
process to which this ACL entry applies. 
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mode 

contains the directory modes for this access name. The first three bits correspond 
to the modes status, modify, and append. The remaining bits must be zeros. For 
example, status permission is expressed as "100"b. The include file 
access_mode_values.incl.pll defines mnemonics for these values: 



del (S ACCESS 


i n i t 


("100"b) , 


M ACCESS 


i ni t 


("010"b) , 


A ACCESS 


i ni t 


("OOT'b) , 


SA ACCESS 


i ni t 


("lOT'b) , 


SM ACCESS 


i ni t 


("1 10"b) ) , 


SMA_ACCESS 


i n i t 


Curb)) , 


bit (3) internal 


static options 


(constant) ; 



status_code 

is a storage system status code for this ACL entry only. 
NOTES 

If code is returned as error_table_$argerr, then the erroneous ACL entries in the 
dir_acl structure have status_code set to an appropriate error code. No processing is 
performed. 



Name: hes Sadd dir inacl entries 

This entry point adds specified directory access modes to the initial access control list 
(initial ACL) for new directories created for the specified ring within the specified 
directory. If an access name already appears on the initial ACL of the directory, its 
mode is changed to the one specified by the call. 

USAGE 

declare hcs_$add_d i r_i nac l_entr i es entry (char (*) , char (») , ptr, 
fixed bin, fixed bin (3), fixed bin (35)); 

call hcs_$add_d i r_i nac gentries (dir_name, entryname, ac1_ptr, 
acl_count, ring, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
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acl_ptr 

points to a user-filled dir_acl_array structure (see "Entry Information" below). 
(Input) 

acl_count 

contains the number of initial ACL entries in the dir_acl_array structure (see 
"Entry Information" below). (Input) 

ring 

is the ring number of the initial ACL. (Input) 

code 

is a storage system status code. (Output) 
ENTRY INFORMATION 

The dir_acl_array structure should be declared in the following way: 
del 1 di r_acl_array (acl_count) aligned like d i r_ac l_entry ; 

The dir_acl_entry structure (declared in the include file acl_structures.incl.pll) is as 
follows: 

del 1 d i r_ac l_entry based, 

2 access_name char (32) unaligned, 

2 mode bit (36) aligned, 

2 status_code fixed bin(35); 

STRUCTURE ELEMENTS 

access_name 

is the access name (in the form Person_id.Project_id.tag) that identifies the 
process to which this initial ACL entry applies. 

mode 

contains the directory modes for this access name. The first three bits correspond 
to the modes status, modify, and append. The remaining bits must be zeros. For 
example, status permission is expressed as "100"b. The include file 
access_mode_values.incl.pll defines mnemonics for these values: 

del (S_ACCESS init ("100"b) , 

M_ACCESS init ( !! 010 !! b) , 

A_ACCESS init ("001 "b) , 

SA_ACCESS init ("101"b) , 

SM_ACCESS init ("110"b)) f 

SMA_ACCESS init ("llT'b)), 

bit (3) internal static options (constant); 



2-389 



AG93-05 



hcs_$add_dir_inacl_entries 



hcs_$add_inacl_entries 



status_code 

is a storage system status code for this initial ACL entry only. 
NOTES 

If code is returned as error_table_$argerr, then the erroneous initial ACL entries in 
the dir_acl structure have status_code set to an appropriate error code. No processing 
is performed in this instance. 



Name: hcs $add inacl entries 

This entry point adds specified access modes to the initial access control list (initial 
ACL) for new segments created for the specified ring within the specified directory. 
If an access name already appears on the initial ACL of the segment, its mode is 
changed to the one specified by the call. 

USAGE 

declare hcs_$add_i nac l_entr i es entry (char (*) , char (*) , ptr, fixed bin, 
fixed bin (3), fixed bin (35)); 

call hcs_$add_i nacl_entr i es (dir_name, entryname, acl_ptr, acl_count, 
r i ng , code) ; 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
acl_ptr 

points to a user-filled segment_acl_array structure (see "Entry Information" below). 
(Input) 

acl_count 

contains the number of initial ACL entries in the segment_acl_array structure (see 
"Entry Information" below). (Input) 

ring 

is the ring number of the initial ACL. (Input) 

code 

is a storage system status code. (Output) 



2-390 



AG93-05 



hcs_$add_inacl_entries 



hcs_$add_inacl_entries 



ENTRY INFORMATION 



The segment_acl_array structure should be 
del 1 segment_acl_array (acl_count) 

The segment_acl_entry structure (declared 
as follows: 



declared in the following way: 
aligned like segment_ac l_entry ; 

in the include file acl_structures. incl.pl!) is 



del 1 segment_acl_entry 
2 access_name 
2 mode 

2 extended_mode 
2 status_code 

STRUCTURE ELEMENTS 



al i gned based, 
char (32) unal i gned, 
bi t (36) al igned, 
bit (36) aligned, 
f i xed b i n (35) ; 



access_name 

is the access name (in the form Person_id.Project_id.tag) that identifies the 
processes to which this initial ACL entry applies. 

mode 

contains the modes for this access name. The first three bits correspond to the 
modes read, execute, and write. The remaining bits must be zeros. For example, 
rw access is expressed as "101"b. The include file access_mode_values.incl.pll 
defines mnemonics for these values: 

del (N_ACCE5S init ( M 000 !! b) , 

R_ACCESS init ("100"b), 

E_ACCESS init ("010"b) , 

W_ACCESS init ("001 "b), 

RE_ACCESS init ("110"b), 

REW_ACCESS init ("1 1 l"b) , 

RW_ACCESS init ("101"b)), 
bit (3) internal static options (constant); 



extended_mode 

should contain the value "0"b. (This field is for use with extended access and 
should only be used in subsystems defining extended access modes). 

O VOL LUJ_WUC 

is a storage system status code for this initial ACL entry only. 
NOTES 

If code is returned as error_table_$argerr, then the erroneous initial ACL entries in 
segment_acl have status_code set to an appropriate error code. No processing is 
performed in this instance. 
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Name: hcs Sappend branch 

The hcs_$append_branch entry point creates a segment in the specified directory, 
initializes the access control list (ACL) of the segment by adding *.SysDaemon.* with 
a mode of rw and adding the initial ACL for segments found in the containing 
directory, and adds the user to the ACL of the segment with the mode specified. 

USAGE 

declare hcs_$append_branch entry (char (*) , char (*) , fixed bin(5), fixed 
bin (35)); 

call hcs_$append_branch (dir_name, entryname, mode, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the segment. (Input) 
mode 

is the user's access mode (see "Notes" below). (Input) 

code 

is a storage system status code. (Output) 
NOTES 

Append permission on the containing directory is required to add a segment to that 
directory. 

A number of attributes of the segment are set to default values as follows: 

1. Ring brackets are set to the user's current validation level. (Ring brackets are 

described in the Programmer's Reference Manual). 

2. The User_id of the ACL entry specifying the given mode is set to the Person_id 

and Projected of the user, with the instance tag set to an asterisk (*). 

3. The copy switch in the branch is set to 0. 

4. The bit count is set to 0. 

See the description of the hcs_$append_branchx entry point to create a storage system 
entry with values other than the defaults listed above. Also see the description of the 
hcs_$append_branchx entry point for values of the access mode argument. 
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Name: hcs Sappend branchx 

The hcs_$append_branchx entry point creates either a subdirectory or a segment in a 
specified directory. It is an extended and more general form of hcs_$append_branch. 
If a subdirectory is created, then the access control list (ACL) of the subdirectory is 
initialized by adding *.SysDaemon.* with a mode of sma and adding the initial ACL 
for directories that is stored in the containing directory; otherwise the ACL of the 
segment is initialized by adding *.SysDaemon.* with a mode of rw and adding the 
initial ACL for segments. The input User_id and mode are then merged to form an 
ACL entry that is added to the ACL of the subdirectory or segment. 

USAGE 

declare hcs_$append_branchx entry (char (*) , char (*) , fixed bin (5), 
(3) fixed bin (3), char (*) , fixed bin(l), fixed bin(l), 
fixed bin (24), fixed bin (35)); 

call hcs_$append_branchx (dir_name, entryname, mode, rings, user_id, 
dir_sw, copy_sw, bit_count, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment or subdirectory. (Input) 
mode 

is the user's access mode (see "Notes" below). (Input) 

rings 

is a three-element array that specifies the ring brackets of the new segment or 
subdirectory. (Input) If a subdirectory is to be created, the third element is 
ignored. (Ring brackets are described in the Programmer's Reference Manual). 

user_id 

is an access control name of the form Person_id.Project_id.tag. (Input) 
dir_sw 

is the branch's directory switch. (Input) 
1 if a directory is being created 
0 if a segment is being created 

copy_sw 

is the value of the copy switch to be placed in the branch. (Input) See the 
Programmer's Reference Manual for an explanation of the copy switch. 

bit_count 

is the segment length (in bits). (Input) 
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code 

is a storage system status code. (Output) 
NOTES 



Append permission is required on the containing directory to add an entry to that 
directory. 

The mode argument is a fixed binary number where the desired mode is encoded with 
one access mode specified by each bit. For segments the modes are: 

read the 8-bit is 1 (i.e., 01000b) 

execute the 4-bit is 1 (i.e., 00100b) 

write the 2-bit is 1 (i.e., 00010b) 



For directories, the modes are: 

status the 8-bit is 1 (i.e., 01000b) 

modify the 2-bit is 1 (i.e., 00010b) 

append the 1-bit is 1 (i.e., 00001b) 



If modify permission is given for a directory, then status must also be given; i.e., 
01010b. 



The unused bits are reserved for unimplemented attributes and must be zero, 
example, rw access is 01010b in binary form. 



For 



The include file access_mode_values.incl.pll defines mnemonics for these values: 



del 



(N_ACCESS 
R_ACCESS" 
E_ACCESS 
W ACCESS" 



BIN 
BIN 
BIN 
BIN 



RW_ACCESS_BIN 
RE_ACCESS_BIN 
REW_ACCESS_BIN 

S_ACCESS_BIN 

M_ACCESS_BIN 

A_ACCESS_BIN 

SA_ACCESS_BIN 

SM_ACCESS_BIN 

SMA ACCESS BIN 



i n 


t 


(00000b) , 


i n 


t 


(01000b) , 


i n' 


t 


(00100b) , 


i n 


t 


(00010b) , 


i n 


t 


(01010b) , 


i n 


t 


(01 100b) , 


i n 


t 


(01 1 10b) , 


i n 


t 


(01000b) , 


i n 


t 


(00010b) , 


i n 


t 


(00001b) , 


i n 


t 


(01001b) , 


i n 


t 


(01010b) , 


i n 


t 


(01011b)) 



fixed bin (5) internal static options (constant); 
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Name: hcs Sappend link 

The hcs_$append_link entry point is provided to create a link in the storage system 
directory hierarchy to some other directory entry in the hierarchy. 

USAGE 

declare hcs_$append_1 ink entry (char (*) , char (*) , char (*) , 
fixed bin (35)) ; 

call hcs_$append_l i nk (dir_name, entryname, path, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the link. (Input) 

path 

is the pathname of the directory entry to which the entryname argument points. 
(Input) The pathname may be a maximum of 168 characters. 

code 

is a storage system status code. (Output) 
NOTES 

Append permission is required in the directory in which the link is being created. 

The entry pointed to by the link need not exist at the time the link is created. 

The hcs_$append_branch and hcs_$append_branchx entry points can be used to create 
a segment or directory entry in the storage system hierarchy. 



Name: hcs__$change be 

This entry point provides a method of changing the bitcount of a segment. It is an 
indivisible operation in that only one process can perform it at a time; thus, if several 
processes try to change the bitcount, each one will get a different output. This can be 
used when several processes must write into a segment; if they use the change_bc 
entrypoint to determine where to write, they will never overwrite each other's data, 
and they will also never have to explicitly manipulate locks. 
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USAGE 

declare hcs_$change_bc entry (char (*) , char (*) , fixed bin (24) , 
fixed bin (24), fixed bin (24), fixed bin (35)); 

call hcs_$change_bc (dir_name, entryname, change, o1d_bc, new_bc, code); 

ARGUMENTS 

diT_name 

is the pathname of the directory containing the segment (Input) 
entryname 

is the entry name of the segment. (Input) 
change 

is the amount by which the bitcount will be changed. (Input) 
old_bc 

is the bitcount before the change was applied. (Output) 
new_bc 

is the bitcount after the change was applied. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have write access to the segment, but need not have modify permission 
on the containing directory. 

The hcs_$change_bc_seg entrypoint performs the same function, but it takes a pointer 
to the segment rather than the pathname. 



Name: hcs $change__bc__seg 

This entry point provides a method of changing the bitcount of a segment. It is an 
indivisible operation in that only one process can perform it at a time; thus, if several 
processes try to change the bitcount, each one will get a different output. This can be 
used when several processes must write into a segment; if they use the change_$bc_seg 
entrypoint to determine where to write, they will never overwrite each other's data, 
and they will also never have to explicitly manipulate locks. 
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USAGE 

declare hcs_$change_bc_seg entry (pointer, fixed bin (24), fixed bin (24), 
fixed bin (24), fixed bin (35)); 

call hcs_$change_bc_seg (seg_ptr, change, old_bc, new_bc, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment whose bitcount is to be changed. (Input) 
change 

is the amount by which the bitcount will be changed. (Input) 
old_bc 

is the bitcount before the change was applied. (Output) 
new_bc 

is the bitcount after the change was applied. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have write access to the segment, but need not have modify permission 
on the containing directory. 

The hcs_$change_bc entry point performs the same function, but it takes the pathname 
of the segment rather than a pointer to it. 



Name: hcs $chname file 

This entry point changes the entry name on a specified storage system entry. If an 
already existing name (an old name) is specified, it is deleted from the entry; if a 
new name is specified, it is added. Thus, if only an old name is specified, the effect 
is to delete a name; if only a new name is specified, the effect is to add a name; 
and if both are specified, the effect is to rename the entry. 

USAGE 

declare hcs_$chname_f i 1 e entry (char (*) , char (*) , char (*) , char (*) , 
fixed bin (35)) ; 

call hcs_$chname_f i 1 e (dir_name, entryname, oldname, newname, code); 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment, directory, multisegment file, or link, (Input) 
oldname 

is the name to be deleted from the entry. (Input) It can be a null character 
string ("") in which case no name is deleted. If oldname is null, then newname 
must not be null. 

newname 

is the name to be added to the entry. (Input) It must not already exist in the 
directory on this or another entry. It can be a null character string ("") in which 
case no name is added. If it is null, then oldname must not be the only name 
on the entry. 

code 

is a storage system status code. (Output) It can have the values: 
error_table_$nonamerr 

attempting to delete the only name of a directory entry. 
error_table_$namedup 

attempting to add a name that exists on another entry. 
error_table_$segnamedup 

attempting to add a name that already exists on this entry. 

NOTES 

The hcs_$chname_seg entry point performs a similar function using a pointer to a 
segment instead of its pathname. 

The user must have modify permission on the directory containing the entry whose 
name is to be changed. 

EXAMPLES 

Assume that the entry >my_dir>work exists and that it also has the entryname Work. 
Then the following call to hcs_$chname_file: 

call hcs_$chname_f i le (">my_dir", "work", "Work", "work2", code); 

changes the entryname Work to work2. The entry now has the names work and 
work2. Another call: 

call hcs_$chname_f i le { ,! >my_dir", "work2", "work2", "", code); 

removes the entryname work2. Either work or work2 could be used in the second 
argument position. The entry now has only the name work. And finally, the call: 
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call hcs_$chname_f i le (">my_dir", "work", "", "wk'\ code); 
adds the entryname wk. The entry now has the names work and wk. 



Name: hcs $chname seg 

This entry point changes an entryname on a segment, if a pointer to the segment is 
given. If an already existing name (an old name) is specified, it is deleted from the 
entry; if a new name is specified, it is added. Thus, if only an old name is specified, 
the effect is to delete a name; if only a new name is specified, the effect is to add 
a name; and if both are specified, the effect is to rename the entry. 

USAGE 

declare hcs_$chname_seg entry (ptr, char ("5 , char (*) , fixed bin (35)); 
call hcs_$chname_seg (seg_ptr, oldname, newname, code); 
ARGUMENTS 
seg_ptr 

is a pointer to the segment whose name is to be changed. (Input) 
oldname 

is the name to be deleted from the entry. (Input) It can be a null character 
string ("") in which case no name is to be deleted. If oldname is null, then 
newname must not be null. 

newname 

is the name to be added to the entry. (Input) It must not already exist in the 
directory on this or another entry. It can be a null character string ("") in which 
case no name is added. If it is null, then oldname must not be the only name 
on the entry. 

code 

is a storage system status code. (Output) It can have the values: 
error_table_$nonamerr 

attempting to delete the only name of a directory entry. 
error_table_$namedup 

attempting to add a name that exists on another entry. 
error_table_$segnamedup 

attempting to add a name that already exists on this entry. 

NOTES 

The hcs_$chname_file entry point performs the same function if the pathname of the 
segment is given instead of a pointer. 
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The user must have modify permission on the directory containing the segment whose 
name is to be changed. 

EXAMPLES 

Assume that the user has a pointer, seg_ptr, to a segment that has two entrynames, 
alpha and beta. Then the following call to hcs_$chname_seg: 

call hcs_$chname_seg (seg_ptr, "beta", "gamma", code); 

changes the entryname beta to gamma. The segment now has the names alpha and 
gamma. Another call: 

call hcs_$chname_seg (seg_ptr, "gamma", "", code); 

removes the entryname gamma. Now the segment only has an entryname of alpha. 
Finally, the call: 

call hcs_$chname_seg (seg_ptr, "", "delta", code); 
adds the entryname delta. The segment now has the names alpha and delta. 



Name: hcs $create branch 

This entry point creates either a subdirectory or a segment in the specified directory. 
(This entry point is an extended and more general form of the hcs_$append_branchx 
entry point.) If a subdirectory is created, then the access control list (ACL) of the 
subdirectory is initiated by copying the initial ACL for directories that is stored in the 
specified directory; otherwise, the ACL of the segment is initiated by copying the 
initial ACL for segments. The access_name and mode items from the create_branch_info 
structure (see "Notes" below) are then added to the ACL of the created subdirectory 
or segment 

USAGE 

declare hcs_$create_branch_ entry (char (*) , char (*) , ptr, 
fixed bin (35)) ; 

call hcs_$create_branch_ (dir_name, entryname, info_ptr, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment or subdirectory to be created. (Input) 
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info_ptr 

is a pointer to the information structure described below. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have append permission on the containing directory to add an entry to 
that directory. 

The info_ptr pointer points to a structure of the following form (found in the include 
file, create_branch_inf o.incl.pll): 

del 1 create_branch_i nf o aligned based, 



2 


vers i on 


fixed bin, 


2 


swi tches 


unal i gned, 




3 dir_sw 


bi t (1) unal i gned, 




3 copy_sw 


bi t (1) unal igned, 




3 chase_sw 


bi t (1) unal igned, 




3 pr i v_upgrade_sw 


bi t (1) unal igned, 




3 parent ac sw 


bi t (1) unal igned, 




3 mbzl 


bi t (3D unal igned, 


2 


mode 


b i t (3) una 1 i gned , 


2 


mbz2 


bi t (33) unal igned, 


2 


r i ngs 


(3) fixed bin (3) , 


2 


user i d 


char (32) , 


2 


bi tent 


f i xed b i n (2k) , 


2 


quota 


fixed bin (18) , 


2 


access_c 1 ass 


bit (72) ; 



STRUCTURE ELEMENTS 
version 

is a number representing the version of the create_branch_info structure being 
used. The caller should set this to create_branch_info_version_l before making 
the call. 

dir_sw 

indicates whether a directory or nondirectory segment is to be created. 
"l"b create a directory segment. 
M 0"b create a nondirectory segment. 

copy_sw 

is the copy switch of the created segment. 

"l"b make a copy whenever the segment is written, if write access is not already 
present. 

"0"b do not make a copy — use the original. 
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chase_sw 

allows creation through links. 

"l"b chase entryname if it is a link and create the desired segment in the final 

directory. 
"0"b do not chase links. 

priv_upgrade_sw 

allows creation of upgraded ring 1 nondirectory segments (i.e., with an access class 
higher than that of the containing directory). The use of this switch is limited to 
ring 1 programs and should normally be "0"b. 

parent_ac_sw 

indicates whether the access class of the parent directory is to be used for the 
created branch. 

"l"b use the access class of the parent. 

"0"b use the access class specified (by access_class described below). 

mbzl 

must be (31)"0"b. 

mode 

is the ACL mode desired for access_name. The meanings of the bits are defined 
in the description of hcs_$add_acl_en tries for segments and hcs_$add_dir_acl_en tries 
for directories. 

mbz2 

must be (33)"0"b. 

rings 

are the desired ring brackets of the new segment or subdirectory. If a 
subdirectory is to be created, the third element is ignored. Ring brackets are 
described in the Programmer's Reference Manual. 

access_name 

is the access control name of the form Person_id.Project_id.tag to be added to 
the ACL. 

bitcnt 

is the length of the segment (in bits), 
quota 

is the desired quota to be moved to the directory created. (It must be 0 for 
nondirectory segments.) If access_class is not equal to the access class of 
dir_name, quota must be greater than 0. 

access_class 

is the desired access class of the directory. For nondirectory segments, access_class 

must be equal to the access class of dir_name unless the priv_upgrade_sw switch 

is set or the parent_ac_sw switch is set. (See the hcs_$get_access_class entry 
point.) 
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Name: hcs $delete_acl entries 

This entry point deletes specified entries from an access control list (ACL) for a 
segment. 

USAGE 

declare hcs_$del ete_ac l_entr i es entry (char (*) , char (*) , ptr, fixed bin, 
fixed bin (35)) ; 

call hcs_$delete_acl_entr ies (dir_name, entryname, acl_ptr, acl_count, 
code) ; 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 
acl_ptr 

points to a user-filled delete_acl_array structure (see "Entry Information" below). 
(Input) 

acl_count 

is the number of ACL entries in the delete_acl_array structure (see "Entry 
Information" below). (Input) 

code 

is a storage system status code. (Output) 
ENTRY INFORMATION 

The delete_acl_array structure should be declared in the following way: 

del 1 delete_acl_array (acl_count) aligned like delete_acl_entry; 

The delete_aci_entry structure (declared in the include file acl_structures.inci.pil) is as 
follows: 

del 1 delete_ad_entry aligned based, 

2 access_name char (32) unaligned, 

2 status_code fixed bin (35); 
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STRUCTURE ELEMENTS 
access_name 

is the access name (in the form of Person_id.Project_id.tag) that identifies the 
ACL entry to be deleted. 

status_code 

is a storage system status code for this ACL entry only. 
NOTES 

If code is returned as error_table_$argerr, then the erroneous ACL entries in the 
delete_acl_array structure have status_code set to an appropriate error code. No 
processing is performed. 

If an access name cannot be matched to a name already on the ACL of the segment, 
then the status_code for that ACL entry in the delete_acl_array structure is set to 
error_table_$user_not_found. Processing continues to the end of the delete_acl_array 
structure and code is returned as 0. 



Name: hcs $delete dir acl entries 

This entry point is used to delete specified entries from an access control list (ACL) 
for a directory. The delete_acl_array structure used by this subroutine is discussed in 
the description of the hcs_$delete_acl_entries entry point. 

USAGE 

declare hcs_$de 1 ete_d i r_ac l_entr i es entry (char (*) , char (&) , ptr, 
fixed bin, fixed bin (35)); 

call hcs_$delete_di r_acl_entr i es (dir_name, entryname, acl_ptr, 
acl_count, code) ; 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
acl_ptr 

points to a user-filled delete_acl_array structure, (input) 
acl_count 

is the number of ACL entries in the delete_acl_array structure. (Input) 
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code 

is a storage system status code (see "Notes" below). (Output) 
NOTES 

If code is returned as error_table_$argerr, then the erroneous ACL entries in the 
delete_acl_array structure have status_code set to an appropriate error code. No 
processing is performed. 

If an access name cannot be matched to a name already on the ACL of the segment, 
then the status_code for that ACL entry in the delete_acl_array structure is set to 
error_table_$user_not_found. Processing continues to the end of the delete_acl_array 
structure and code is returned as 0. 



Name: hcs Sdelete dir inacl entries 

This entry point is used to delete specified entries from an initial access control list 
(initial ACL) for new directories created for the specified ring within the specified 
directory. The delete_acl_array structure used by this subroutine is described in the 
hcs_$delete_acl_entries entry point. 

USAGE 

declare hcs_$del ete_d i r_i nac l_entr i es entry (char (*) , char (*) , ptr, 
fixed bin, fixed bin (3), fixed bin (35)); 

call hcs_$delete_di r_inacl_entr ies (dir_name, entryname, acl_ptr, 
acl_count, ring, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
acl_ptr 

points to the user-filled delete_acl_array structure. (Input) 
acl_count 

is the number of initial ACL entries in the delete_acl_array structure. (Input) 

ring 

is the ring number of the initial ACL. (Input) 
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code 

is a storage system status code. (Output) 
NOTES 

If code is returned as error_table_$argerr, then the erroneous initial ACL entries in 
the delete_acl_array structure have status„code set to an appropriate error code. No 
processing is performed in this instance. 

If an access_name in the delete_acl_array structure cannot be matched to one existing 
on the initial ACL, then the status_code of that initial ACL entry in the 
delete_acl_array structure is set to error_table_$user_not_found. Processing continues to 
the end of the delete_acl_array structure and code is returned as 0. 



Name: hcs Sdelete inacl_entries 

This entry point is called to delete specified entries from an initial access control list 
(initial ACL) for new segments created for the specified ring within the specified 
directory. The delete_acl_array structure used by this subroutine is discussed in the 
hcs_$delete_acl_entries entry point. 

USAGE 

declare hcs_$delete_i nacl_entr i es entry (char («) , char (*) , ptr, 
fixed bin, fixed bin(3), fixed bin(35)); 

call hcs_$del ete_i nac l_entr i es (dir_name, entryname, acl_ptr, acl_count, 
r i ng, code) ; 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
acl_ptr 

points to the user-filled delete_acl_array structure. (Input) 
acl_count 

contains the number of initial ACL entries in the delete_acl_array structure. 
(Input) 

ring 

is the ring number of the initial ACL. (Input) 
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code 

is a storage system status code. (Output) 
NOTES 

If code is returned as error_table_$argerr, then the erroneous initial ACL entries in 
the delete_acl_array structure have status_code set to an appropriate error code. No 
processing is performed in this instance. 

If an access_name in the delete_acl_array structure cannot be matched to one existing 
on the initial ACL, then the status_code of that initial ACL entry in the 
delete_acl_array structure is set to error_table_$user_not_found. Processing continues to 
the end of the delete_acl_array structure and code is returned as 0. 



Name: hcs $force write 

This entry point causes the supervisor to force modified pages out of main memory 
protecting data against an unrecoverable main memory crash. 

USAGE 

declare hcs_$f orce_wr i te entry (ptr, bit (36), fixed bin (35)); 

call hcs_$f orce_wr i te (segp, flags, code); 

ARGUMENTS 

segp 

is a pointer to the segment whose modified pages are to be written. (Input) 

flags 

specify a set of options. (Input) Currently only one option is defined. The 
following structure (also defined in the system include file force_write_flap.incl.pll) 
defines the options: 

del 1 f orce_wr i te_opt i ons based (addr (flags)) unaligned, 

2 mbzl bi t (1) , 

2 ser i al_wr i te bi t (1) , 

2 mbz2 ~ bit(3i*); 

serial_write: 

"0"b queue write requests for all modified pages in parallel, up to the maximum 
permitted by the supervisor's force-write limit (see 
shcs_$set_f orce_write_limit). 

"l"b queue write requests for all modified pages serially (i.e., one at a time). 
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mbzl, mbz2 

these fields must be zero. 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$bad_ring_brackets 

the segment is an inner ring segment. 
error_table_$moderr 

the user does not have write access to the segment. 
error_table_$invalidsegno 

the segment is not known, not active, or a hardcore segment. This should not 

be treated as an error because the user has no control over whether or not 

the segment is active. 

NOTES 

Use of this entry point may introduce substantial real time delay into execution, since 
the caller must wait for the movement of the disk; other usage of the system, 
meanwhile, may cause further delay. 



Name: hcs $fs get access modes 

This entry point returns the user's access mode and extended access mode on a 
specified segment at the current validation level. For a discussion of access modes see 
"Access Control" in the Programmer's Reference Manual. 

USAGE 

declare hcs_$f s_get_access_modes entry (ptr, bit (36) aligned, bit (36) 
aligned, fixed bin (35)); 

call hcs_$f s_get_access_modes (seg_ptr, modes, ex_modes, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment whose access mode is to be returned. (Input) 
modes 

is the returned access mode. See the description of the hcs_$append_branchx 
entry point for the values of the mode argument. (Output) 

ex_modes 

is the returned extended access mode. (Output) 
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code 

is a storage system status code. (Output) 
NOTES 

The mode and ring brackets for the segment in the user's address space are used in 
combination with the user's current validation level to determine the mode the user 
would have if he accessed this segment For a discussion of ring brackets and 
validation level, see "Intraprocess Access Control" in the Programer's Reference 
Manual. 



Name: hcs $fs get mode 

This entry point returns the user's access mode on a specified segment at the current 
validation level. For a discussion of access modes see the Programmer's Reference 
Manual. 

USAGE 

declare hcs_$f s_get_mode entry (ptr, fixed bin (5), fixed bin (35)); 

call hcs_$f s_get_mode (seg_ptr, mode, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment whose access mode is to be returned. (Input) 
mode 

is the returned access mode (see "Notes" below). (Output) 

code 

is a storage system status code. (Output) 
NOTES 

The mode and ring brackets for the segment in the user's address space are used in 
combination with the user's current validation level to determine the mode the user 
would have if he accessed this segment. For a discussion of ring brackets and 
validation level see the Programmer's Reference Manual. 
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See the description of the hcs_$append_branchx entry point for the values of the 
mode argument. 



Name: hcs^Sfs^get^path^name 

The hcs_$fs _get_path_name entry point, given a pointer to a segment, returns a 
pathname for the segment, with the directory and entryname portions of the pathname 
separated. The entryname returned is the primary name on the entry. For a definition 
of "primary name" refer to "Glossary of Multics Terms" in the Programmer's 
Reference Manual. 

USAGE 

declare hcs_$f s_get_path_name entry (ptr, char (*) , fixed bin, char (*) , 
fixed bin (35)) ; 

i i i f -c *. u I ~ i a~ ^^+- .. w~ . 

CO I l m_a v i => yci paLii name \-=<^y pci » w i i namb, iuii, ciili ; name, luuc / , 

seg_ptr 

is a pointer to the segment. (Input) 
dir_name 

is the pathname of the containing directory. (Output) If the length of the 
pathname to be returned is greater than the length of dir_name, the pathname is 
truncated. To avoid this problem, the length of dir_name should be 168 
characters. 

Idn 

is the number of nonblank characters in dir_name. (Output) 
entryname 

is the primary entryname of the segment. (Output) If the length of the 
entryname to be returned is greater than the length of entryname, the entryname 
is truncated. To avoid this problem, the length of entryname should be 32 
characters. 

code 

is a storage system status code. (Output) 
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Name: hcs $fs get ref name 

This entry point returns a specified (i.e., first, second, etc.) reference name for a 
specified segment 

USAGE 

declare hcs_$f s_get_ref_name entry (ptr, fixed bin, char (*) , 
fixed bin (35)) ; 

call hcs_$f s_get_ref_name (seg_ptr, count, ref_name, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment whose reference name is sought. (Input) 
count 

specifies which reference name is to be returned, where 1 is the name by which 
the segment has most recently been made known, 2 is the next most recent name, 
etc. (Input) 

ref_name 

is the desired reference name. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

If the count argument is larger than the total number of names, the name which the 
segment was originally made known is returned and code is set to 
error_table_$refname_count_too_big. 



Name: hcs $fs get seg ptr 

This entry point, given a reference name of a segment, returns a pointer to the base 
of the segment. 

USAGE 

declare hcs_$f s_get_seg_ptr entry (char (*) , ptr, fixed bin(35))» 
call hcs_$f s_get_seg_ptr (ref_name, seg_ptr, code); 
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ARGUMENTS 
ref_name 

is the reference name of a segment for which a pointer is to be returned. 
(Input) 

scg ptr 

is a pointer to the base of the segment. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

If the reference name is accessible from the user's current validation level, seg_ptr is 
returned pointing to the segment; otherwise, it is null. For more information on rings 
and validation levels refer to the Programmer's Reference Manual. 



Name: hcs $fs move file 

This entry point moves the data associated with one segment in the storage system 
hierarchy to another segment given the pathnames of the segments in question. The 
old segment remains, but with a zero length. 

USAGE 

declare hcs_$f s_move_f i 1 e entry (char (*) , char (*) , fixed bin (2), 
char (*) , char (*) , fixed bin (35)); 

call hcs_$ f s_move_f i 1 e (f rom_d i r , f rom_entry , at_sw, to_dir, to_entry, 
code) ; 

ARGUMENTS 

from_dir 

is the pathname of the directory in which from_entry resides. (Input) 
from_entry 

is the entryname of the segment from which data is to be moved. (Input) 
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at_sw 

is a 2-bit append /truncate switch. (Input) 
append (first bit): 

0 if to_entry does not exist, the code error_table_$noentry is returned 

1 if to_entry does not exist, it is created 

truncate (second bit): 

0 if to_entry is not a zero-length segment, the code error_table_$clnzero is 
returned 

1 if to_entry is not a zero-length segment, it is truncated before moving 
to_dir 

is the pathname of the directory in which to_entry resides. (Input) 
to_entry 

is the entryname of the segment to which data is to be moved. (Input) 

code 

is a storage system status code. (Output) It can have the value error_table_$no_move 
for any of the reasons described in "Notes" below. 

NOTES 

The hcs_$fs_move_seg entry point performs the same function given pointers to the 
segments in question instead of pathnames. 

The code error_table_$no_move is returned if: 

1. Either to_entry or from_entry is not a segment. 

2. The user does not have rw access to to_entry. 

3. The user does not have read access to from_entry. 

4. The maxjength of to_entry is less than the length of from_entry. 

5. There is not enough quota in to_dir to perform the move. 
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Name: hcs_$fs move seg 

This entry point moves the data associated with one segment in the hierarchy to 
another segment, given pointers to the segments in question. The old segment remains, 
but with a zero length. 

USAGE 

declare hcs_$f s_move_seg entry (ptr, ptr, fixed bin(l), fixed bin (35))* 

call hcs_$f s_move_seg (from_ptr, to_ptr, trun_sw, code); 

ARGUMENTS 

from_ptr 

is a pointer to the segment from which data is to be moved. (Input) 
to_ptr 

is a pointer to the target segment. (Input) 
trun_sw 

indicates whether the segment specified by to_ptr is to be truncated (if it is not 
already zero length) before performing the move. (Input) 

0 returns code error_table_$clnzero if the segment is not already zero length 

1 truncates the segment before moving 

code 

is a storage system status code. (Output) It can have the value error_table_$no_move 
or error_table_$clnzero. 

NOTES 

The hcs_$fs_move_fi!e entry point performs the same function given the pathnames of 
the segments instead of the pointers. 



Name: hcs $get access__class 

This entry point returns the access class of a segment or directory in the storage 
hierarchy. For information on access classes, see the Programmer's Reference Manual. 

USAGE 

declare hcs_$get_access class entry (char (*) , char (*) , bit (72) aligned, 
fixed bin (35)) ? 

call hcs_$get_access__cl ass (dir_name, entryname, access_c 1 ass , code); 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment or directory. (Input) 
access_class 

is the access class of the segment or directory. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

If the value of entryname is null, dir_name is assumed to be a full pathname. 

The user must have status permission on the directory (the dir_name argument) or 
nonnull access to the entry (the entryname argument). 



Name: hcs Sget access class seg 

This entry point, given a pointer, returns the access class of that pointer's 

corresponding segment. For information on access classes, see the Programmer's 
Reference Manual. 

USAGE 

declare hcs_$get_access_cl ass_seg entry (ptr, bit (72) aligned, 
fixed bin(35)) ; 

call hcs_$get_access_c 1 ass_seg (seg_ptr , accessed ass, code); 

ARGUMENTS 

seg_ptr 

is the pointer to the segment (Input) 
access_class 

is the access class of the segment. (Output) 

code 

is a storage system status code. (Output) 
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Name: hcs__$get__access info 

This entry point returns all of the access attributes of a storage system object, given 
its pathname. 

USAGE 

declare hcs_$get_access_i nf o entry (char (») ♦ char (*) , fixed bin(l), ptr, 
fixed bin (35))-; 

call hcs_$get_access__i nf o (di r_name, entryname, chase, 
entry_access_i nf o_ptr , code); 

ARGUMENTS 

dir_name 

the directory containing the object about which information is to be returned. 
(Input) 

entryname 

the entryname of the object (Input) 

chase 

indicates the action hcs_$get_access_info is to perform if the object is a link. 
(Input) Its possible values are: 

0 do not chase the link 

1 chase the link. 

entry_access_inf o_ptr 

points to a structure containing all the access information for the object (Input) 

code 

is a standard system status code. (Output) Its possible values are: 
error„table_$link 

if chase was not specified, then the pathname supplied is a link. Otherwise, 
the pathname supplied eventually points to a null link. 

error_table_$null_inf o_ptr 

the entry_access_info_ptr supplied was null. 

error_table_$unimplemented_version 

the requested version of entry_access_info is not supported. 
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NOTES 



The following structure, declared in entry_access_info.incl.pll, is pointed to by 
entry_access_inf o_ptr: 



del 1 



2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 



entry_access_i nfo aligned based (entry_access_i nf o_ptr) , 

vers ion char (8) , 

type fixed bin, 

dir_name char ( 1 68) unaligned, 

entryname char (32) unaligned, 

uid bit (36) aligned, 

r i ng_brackets (3) fixed bin (3), 

extended_r i ng_brackets (3) fixed bin (3), 

ef f ect i ve_access_modes bit (36) aligned, 

extended_access__modes bit (36) aligned, 

access_class bit (72) aligned, 

parent_access_cl ass bit (72) aligned, 

multiclass bit (1) aligned; 



STRUCTURE ELEMENTS 
version 

must be set to ENTRY_ACCESS_INF0_VERSI0N_1. 

type 

specifies the type of the object. Its possible values are: 

0 link 

1 segment 

2 directory 

dir_name 

the pathname of the entry's parent. 

entryname 

primary name of the . entry 

uid 

the entry's unique identifer 
ring_brackets 

the entry's ring brackets. For directories, ring_brackets(3) is not used. 

extended_ring_brackets 

this has not been implemented. 

ef f ecti ve_access_modes 

the user's effective access to this entry, taking into account ACLs, ring brackets, 
and AIM authorization. 
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extended_access_modes 

the user's extended access modes to this entry. 

access_class 

the access class of the object. If it is a multiclass object, the maximum access 
class from which the object can be referenced. 

parent_access_class 

the access class of the object's parent. For a multiclass object, the minimum 
access class from which the object can be referenced. 

multiclass 

is "l"b if the object is multiclass 

ACCESS REQUIRED 

This entrypoint requires s access to the containing directory of the object, or non-null 
access to the object itself. 



Name: hcs $get access info seg 

This entry point returns all of the access attributes of a storage system object, given a 
pointer to the segment. 

USAGE 

declare hcs_$get_access_i nf o_seg entry (ptr, ptr, fixed bin (35)) S 
call hcs_$get_access_i nf o_seg (segjptr, entry_access_i nf o_ptr , code); 
ARGUMENTS 
seg_ptr 

is a pointer to the segment about which information is to be returned. 

entry_access_inf o_ptr 

points to a structure containing all the access information for the object (Input) 

code 

is a standard system status code. (Output) Its possible values are: 

error_table_$null_inf o_ptr 

the entry_access_info_ptr supplied was null. 

error_table_$unimplemented_version 

the requested version of entry_access_info is not supported. 
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NOTES 

The following structure, declared in entry_access_info.incl.pli, is pointed to by 
entry_access_inf o_ptr: 

del 1 entry_access_i nf o aligned based (entry_access_i nfo_ptr) , 

2 version char (8) , 

2 type fixed bin, 

2 dir_name char (168) unaligned, 

2 entryname char (32) unaligned, 

2 uid bit (36) al igned, 

2 r i ng_brackets (3) fixed bin (3), 

2 extended_r i ng_brackets (3) fixed bin (3), 

2 ef f ect i ve__access_modes bit (36) aligned, 

2 extended_access_modes bit (36) aligned, 

2 access_class bit (72) aligned, 

2 parent_access_c lass bit (72) aligned, 

2 multiclass bit (1) aligned; 

STRUCTURE ELEMENTS 

version 

must be set to ENTRY_ACCESS_INF0_VERSI0N_1. 

type 

specifies the type of the object Its possible values are: 

1 segment 

2 directory 

dir_name 

the pathname of the entry's parent. 

entryname 

primary name of the entry 

uid 

the entry's unique identifer 
ring_brackets 

the entry's ring brackets. For directories, ring_brackets(3) is not used. 

extended_ring_brackets 

this has not been implemented. 

ef f ecti ve_access_modes 

the user's effective access to this entry, taking into account ACLs, ring brackets, 
and AIM authorization. 

extended_access_modes 

the user's effective extended access mode to this entry. 
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access_class 

the access class of the object. If it is a multiclass object, the maximum access 
class from which the object can be referenced. 

parent_access_class 

the access class of the object's parent For a multiclass object, the minimum 
access class from which the object can be referenced. 

multiclass 

is 'T'b if the object is multiclass 

ACCESS REQUIRED 

This entrypoint requires s access to the containing directory of the object, or non-null 
access to the object itself. 



Name: hcs Sget author 

This entry point returns the author of a segment, directory, multisegment file, or link. 
USAGE 

declare hcs_$get_author entry (char (*) , char (*) , fixed bin(l), char (*) , 
fixed bin (35)) ; 

call hcs_$get_author (dir_name, entryname, chase, author, code); 

ARGUMENTS 

dir_name 

is the pathname of the directory. (Input) 
entryname 

is the entry name of the segment, directory, multisegment file, or link. (Input) 
chase 

if entryname refers to a link, this flag indicates whether to return the author of 
the link or the author of the segment, directory, or multisegment file to which 
the link points. (Input) 

0 return link author. 

1 return segment, directory, or multisegment file author. 
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author 

is the author of the segment, directory, multisegment file, or link in the form of 
Person_id.Project_id.tag with a maximum length of 32 characters. (Output) An 
error is not detected if the string is too short on hold the author. 

code 

is a storage system status code. (Output) 



NOTES 



The user must have status permission on the directory or non-null access on the entry. 
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Name: hcs $get be author 

This entry point returns the bit count author of a segment or directory. The bit 
count author is the name of the user who last set the bit count of the segment or 
directory. 

USAGE 

declare hcs_$get_bc_author entry (char («) , char (*) , char (*) , 
fixed bin (35) ) ; 

call hcs_$get_bc_author (dir_name, entryname, bc_author, code); 

ARGUMENTS 

dir_name 

is the pathname of the directory. (Input) 
entryname 

is the entry name of the segment or directory. (Input) 
bc_author 

is the bit count author of the segment or directory in the form of 
Person_id.Project_id.tag with a maximum length of 32 characters. (Output) An 
error is not detected if the string is too short to hold the bit count author. 

code 

is a storage system status code. (Output) 
NOTES 

The user must have status permission on the directory or non-null access on the entry. 



Name: hcs Sget dir ring brackets 

This entry point, when given the pathname of a containing directory and the 
entryname of a subdirectory, returns the value of that subdirectory's ring brackets. 

USAGE 

declare hcs_$get_d i r_r i ng_brackets entry (char (*) , char (*) , 
(2) fixed bin (3), fixed bin (35)); 

call hcs_$get_d i r_r i ng_brackets (dir_name, entryname, drb, code); 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entry name of the subdirectory. (Input) 

drb 

is a two-element array that contains the directory's ring brackets. (Output) The 
first element contains the level required for modify and append permission; the 
second element contains the level required for status permission. 

code 

is a storage system status code. (Output) 
NOTES 

The user must have status permission on the directory or non-null access on the entry. 

Ring brackets are discussed in "Intraprocess Access Control" in the Programmer's 
Reference Manual. 



Name: hcs $get exponent control 

This entry point returns the current settings of the flags that control the system's 
handling of exponent overflow and underflow conditions. For more information on 
exponent control see the description of hcs_$set_exponent_control. 

USAGE 

declare hcs_$get_exponent_control entry (bit(l) aligned, bit(l) aligned, 
float bin (63)) ; 

call hcs_$get_exponent_control (restart_underf low, restart_overf low, 
over f 1 ow_val ue) ; 

ARGUMENTS 
restart_underflow 

is "l"b if underflows are currently being automatically restarted, and "0"b 
otherwise. (Output) 

restart_overflow 

is "l"b if overflows are currently being automatically restarted, and "0"b 
otherwise. (Output) 
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overflow_value 

is the value used for the result of the computation in the case of overflow. 
(Output) 



Name: hcs__$get initialling 

This entry point returns the ring at which the process was logged in. 
USAGE 

declare hcs_$get_i ni t i al_r i ng entry (fixed bin); 
call hcs_$get_initial_r ing (initialling); 
ARGUMENTS 
initialling 

the ring number at which the process began execution. (Output) 
ACCESS REQUIRED 
No access is required. 



Name: hcs Sget ips mask 

This entry point returns the value of the current ips mask. 
USAGE 

declare hcs_$get_i psjnask entry (bit (36) aligned); 

call hcs_$get_J ps_mask (old_mask) ; 

ARGUMENTS 

old_mask 

is the current value of the ips mask. (Output) 
NOTES 

A "l"b in any position in the mask means that the corresponding ips interrupt is 
enabled. 
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The thirty-sixth (rightmost) bit of old_mask does not correspond to an interrupt, but 
is used as a control bit, giving a positive indication that a particular masking or 
unmasking operation has taken place. No ips interrupts can occur in the time interval 
between the requested mask modification and the returning of the old_mask, with the 
control bit set appropriately. 

Entry points used at the beginning of a critical section of code, to disable some or all 
ips interrupts, return a value of "l"b for the control bit, while those that are used at 
the end of a critical section of code, to re-enable those interrupts, return a value of 
"0"b for the control bit Thus, a condition handler can interpret a value of 'T'b in 
the control bit as meaning that execution was in a critical section of code, and the 
ips mask has been modified. 

The control bit in the mask returned by this entry point is always "0"b. 



Name: hcs__ $get__link_target 

This entry point returns the pathname of the ultimate target of a link if the ultimate 
target exists, or what that pathname would be if the target did exist. 

USAGE 

declare hcs_$get__l i nk_target entry (char (*) , char (*) , char (*) , char (*) , 
fixed bin (35)) ; 

call hcs__$get_l i nk_target (dir_name, entryname, 1 i nk_d i r_name, 
1 i nk_entryname, code) ; 

ARGUMENTS 

dir_name 

is the directory name containing the link. (Input) 
entryname 

is the entryname of the link for which target information is desired. (Input) 
link_dir_name 

is the directory name of the link target with a maximum length of 168 characters. 
(Output) 

link_entryname 

is the entryname of the link target with a maximum length of 32 characters. 
(Output) 

code 

is a standard status code, (Output) 
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NOTES 

This entry chases the link to its ultimate target. The ultimate target of a link must be 
a directory or segment, which may or may not exist. If the immediate target of a 
link is another link, the chasing of links continues toward the ultimate target directory 
or segment until it is encountered or found to be nonexistent If the ultimate target 
of the link exists, the user must either have nonnull permission on the directory | 
containing the target or nonnull access to the target itself in order to determine its 
pathname. If appropriate access exists, the code is zero, and link_dir_name and 
link_entryname are set. If not, an error code is returned, and the link_dir_name and 
link_entryname are returned as blank. 

If the ultimate target does not exist, the target pathname of the last link encountered 
while chasing links will be returned if the user has nonnull permission on the 
directory that would have contained that target pathname. In this case, the returned 
code is error_table_$noentry, and the link_dir_name and link_entryname are set. 
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In all other cases, an error code is returned to indicate the lack of access, and 
link_dir_name and link_entryname are returned as blanks. 



Name: hcs $get max length 

This entry point, given a directory name and entryname, returns the maximum length 
(in words) of the segment 

USAGE 

declare hcs_$get_max_l ength entry (char (*) , char (*) , fixed bin(19)» 
fixed bin (35)) ; 

call hcs_$get_max_l ength (dir_name, entryname, max_length, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 
max_length 

is the maximum length of the segment in words. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have status permission on the directory containing the segment or 
nonnull access to the segment. 
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Name: hcs $get max length_seg 

This entry point, given a pointer to a segment, returns the maximum length (in words) 
of the segment. 

USAGE 

declare hcs_$get_max_length_seg entry (ptr, fixed bi n (19) » 
fixed bin (35)) ; 

call hcs_$get_max_l ength_seg (seg_ptr, max_length, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment whose maximum length is to be returned. (Input) 
max_length 

is the maximum length of the segment in words. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have status permission on the directory containing the segment or 
nonnull access to the segment 



Name: hcs Sget page trace 

The hcs_$get_page_trace entry point returns information about recent paging activity. 
USAGE 

declare hcs_$get_page_trace entry (ptr); 
call hcs_$get_page_trace (data_ptr) ; 
ARGUMENTS 
data_ptr 

is a pointer to a user data space where return information is stored. (Input) 
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NOTES 



The format of the data structure returned by hcs_$get_page_trace is described below. 
The amount of data returned cannot be known in advance other than that there are 
less than 1024 words returned. 

del 1 trace aligned based (tp) 

2 next_avai lable bit(l8) aligned, 

2 s i ze b i t ( 1 8) all gned, 

2 time fixed bin (71) , 

2 padl fixed bin (35) * 

2 i ndex bi t (17) , 

2 pad2 fixed bin (71) , 

2 data (512 refer(divide (trace. size, 2, 17,0) )) , 

3 info bit(36) aligned, 

3 type bit (6) unaligned 

3 pageno bit (12) unaligned, 

3 time_delta bit(l8) unaligned; 

STRUCTURE ELEMENTS 



next_available 

is a relative pointer (relative to the first trace entry) to the next entry to be 
used in the trace list. 

size 

is the number of words in the trace array and, hence, twice the number of 

entries in the array. 

time 

is the real-time clock reading at the time the last trace entry was entered in the 
list. 



padl 

is unused, 
index 

is a relative pointer to the first trace entry entered in the last quantum. Thus, all 
events traced in the last quantum can be determined by scanning from trace. index 
to trace.next_available (minus 1) with the obvious check for wrap-around. 



pad2 

is unused. 



info 

is information about the particular trace entry. 
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type 

specifies what kind of a trace entry it is. The following types are currently 



defined* 




0 


page fault 


2 


segment fault begin 


3 


segment fault end 


4 


linkage fault begin 


5 


linkage fault end 


6 


bound fault begin 


7 


bound fault end 


8 


signaller event 


9 


restarted signal 


10 


reschedule 


11 


user marker 


12 


interrupt 



pageno 

is the page number associated with the fault. Certain trace entries do not fill in 
this field. 

time_delta 

is the amount of real time elapsed between the time this entry was entered and 
the previous entry was entered. The time value is in units of 64 microseconds. 



Name: hcs__$get process usage 

This entry point returns information on system resource usage by the requesting 
process. 

USAGE 

declare hcs_$get_process_usage entry (ptr, fixed bin (35)); 

call hcs_$get_process_usage (process_usage_poi nter , code); 

ARGUMENTS 

process_usage_pointer 

is a pointer to the structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 
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NOTES 



The following structure, declared in process_usage.incl.pll, is pointed to by 
process_usage_pointer: 

del 1 process_usage based (process_usage_poi nter) , 

2 number_wanted fixed bin, 

2 number_can_return fixed bin, 

2 cpu_time fixed bin (71) , 

2 pag i ng_measure fixed bin (71) » 

2 page_faults fixed bin (3^), 

2 pd_faults fixed bin (3*0, 

2 vi rtual_cpu_t ime fixed bin (71) , 

2 segment_f aul ts fixed bin (3*0 , 

2 bounds_f aul ts fixed bin (3*0, 

2 vtoc_reads fixed bin (3*0, 

2 vtoc writes fixed bin (3*0; 



STRUCTURE ELEMENTS 



number_wanted 

specifies how much information is to be returned in the structure. It must be set 
prior to the call to hcs_$get_process_usage, and its interpretation is given below. 
It is the only input parameter in the structure; all other items are output from 
hcs_$get_process_usage or are ignored, depending on the value of number_wanted. 

number_can_return 

is the number of system resource values which can be returned. It corresponds to 
the number of level 2 items in the structure following number_can_return. This is 
returned for all values of number_wanted. 

cpu_time 

is the cumulative central processor time for the process. It includes all time spent 
executing instructions outside of ring 0, all time spent executing instructions in 
ring 0 as the result of explicit calls to ring 0, and all overhead time while 
executing instructions in the address space of this process (e.g., processing page 
faults for this process and interrupts where this process was interrupted). This is 
returned if number_wanted is 1 or greater. 

paging_measure 

is the cumulative memory usage for the process in billable memory units. This is 
returned if number_wanted is 2 or greater. 

page_faults 

is the cumulative number of page faults by the process. This number represents 
the number of times a page was referenced which was not in main memory. This 
is returned if number_wanted is 3 or greater. 
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pd_faults 

is the cumulative number of paging device faults by the process. This number is 
always zero. This is returned if number_wanted is 4 or greater. 

virtual_cpu_time 

is the cumulative virtual time for the process. This includes all time spent 
executing instructions outside of ring 0 and all time spent executing instructions in 
ring 0 as the result of explicit calls to ring 0. It does not include overhead time, 
such as the time spent processing page faults, segment faults, or interrupts. This 
is returned if number_wanted is 5 or greater. 

segment_faults 

is the cumulative number of segment faults by the process. This represents the 
number of times a segment was referenced whose page table was not in main 
memory. This is returned if number_wanted is 6 or greater. 

bounds_faults 

is the cumulative number of bounds faults by the process. This represents the 
number of times an address within a segment was referenced that was beyond the 
segment bound. This occurs most commonly when a segment expands to the point 
where it requires a larger page table. This is returned if number_wanted is 7 or 
greater. 

vtoc_reads 

is the number of read I/Os done by the process to Volume Table of Contents 
Entries (VTOCEs). This is returned if number_wanted is 8 or greater. 

vtoc_writes 

is the number of write I/Os done by the process to VTOCEs. This is returned if 
number_wanted is 9 or greater. 

NOTES 

In the above description, cumulative activity by the requesting process is defined to 
mean all activity since login or since the most recent new_proc. 
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Name: hcs $get ring__brackets 

This entry point, given the directory name and entryname of a segment, returns the 
value of that segment's ring brackets. 

USAGE 

declare hcs_$get ring brackets entry (char (*) , char (*) , (3) fixed 
bin(3), " . 
fixed bin(35)) ; 

call hcs_$get_r i ng_brackets (dir_name, entryname, rb, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment (Input) 

rb 

is a three-element array that contains the segment's ring brackets. (Output) Ring 
brackets and validation levels are discussed in "Intraprocess Access Control" in the 
Programmer's Reference Manual. 

code 

is a storage system status code. (Output) 
NOTES 

The user must have status permission on the directory or non-null access to the entry. 



Name: hcs Sget ring brackets seg 

This entry point, given a pointer to a segment, will return the ring brackets of the 
segment. 

USAGE 

declare hcs_$get_r i ng__brackets entry (ptr, (3) fixed bin (3), fixed 
bin (35)); 

call hcs_$get_r i ng_brackets (seg_ptr, brackets, code); 
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ARGUMENTS 
seg_ptr 

is a pointer to the segment in question. (Input) 
brackets 

is a three-element array that contains the segment's ring brackets. (Output) Ring 
brackets and validation levels are discussed in "Intraprocess Access Control" in the 
Programmer's Reference Manual. 

code 

is a storage system status code. (Output) 
ACCESS REQUIRED 

The user must have status permission on the directory or non-null access to the 
object. 



Name: hcs $get safety sw 

This entry point, given a directory name and an entryname, returns the value of the 
safety switch of a directory or a segment. 

USAGE 

declare hcs_$get_saf ety_sw entry (char (*) , char (*) , bit(l), 
fixed bin (35)) ; 

call hcs_$get_saf ety_sw entry (dir_name, entryname, safety_sw, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory or segment (Input) 
saf ety_sw 

is the value of the safety switch. (Output) 
"0"b the segment or directory can be deleted. 
"l"b the segment or directory cannot be deleted. 

code 

is a storage system status code. (Output) 
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NOTES 

The user must have status permission on the containing directory or nonnull access to 
the directory or segment 



Name: hcs $get__safety sw seg 

This entry point, given a pointer to the segment, returns the value of the safety 
switch of a segment 

USAGE 

declare hcs_$get_saf ety_sw_seg entry (ptr, bit(l), fixed bin (35)) » 
call hcs_$get_saf ety_sw_seg (seg_ptr, safety_sw, code); 
ARGUMENTS 
seg_ptr 

is a pointer to the segment whose safety switch is to be examined. (Input) 
safety_sw 

is the value of the segment safety switch. (Output) 
"0"b the segment can be deleted. 
"l"b the segment cannot be deleted. 

code 

is a storage system status code. (Output) 
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hcs_$get_saf ety_sw_seg hcs_$get_search_rules 
NOTES 

The user must have status permission on the directory containing the segment or must 

have nonnull access to the segment. 



Name: hcs $get search rules 

This entry point returns the search rules currently in use in the caller's process. 
USAGE 

declare hcs__$get_search_rul es entry (ptr) ; 
call hcs_$get_search_rul es (search_rul es_ptr) ; 
ARGUMENTS 
search_rules_ptr 

is a pointer to a user-supplied search rules structure. (Input) See "Note" below. 
NOTES 

The structure pointed to by search_rules_ptr is declared as follows: 

del 1 search_rules aligned, 

2 number fixed bin, 

2 names (21) char(l68) aligned; 

STRUCTURE ELEMENTS 

number 

is the number of search rules in the array, 
names 

are the names of the search rules. They can be absolute pathnames of directories 
or keywords. (See the hcs_$initiate_search_rules entry point for a detailed 
description of the search rules.) 
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Name: hcs $get system search rules 

This entry point provides the user with the values of the site-defined search rule 
keywords accepted by hcs_$initiate_search_rules. 

USAGE 

declare hcs_$get_system_search_rul es entry (ptr, fixed bin (35)); 
call hcs_$get_system_search_rul es (search_rul es_ptr , code); 
ARGUMENTS 
search_rules_ptr 

is a pointer to the structure described in "Notes" below. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

The structure pointed to by search_rules_ptr is declared as follows: 

del 1 drules based aligned, 

2 ntags fixed bin, 

2 nrules fixed bin, 
2 tags (10) , 

3 name char (32) , 

3 flag bit (36) , 
2 rules (50) , 

3 name char ( 1 68) , 

3 flag bit (36) ; 

STRUCTURE ELEMENTS 
ntags 

is the number of tags, 
nrules 

is the number of rules. 

tap 

is an array of keywords. 

tags, name 

is the keyword. 

tags, flag 

is a bit field with one bit on. 
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rules 

is an array of directory names, 
rules, name 

is the absolute pathname of the directory, 
rules, flag 

is a bit field with bits on for every tag that selects this directory. 



Name: hcs $get uid file 

This entry point returns the unique identifier of a storage system entry. If the input 
arguments refer to a link, the uid of the target is returned. 

USAGE 

dec 1 age hcs_$get_u i d_f i 1 e entry (char (*) , char (*) , bit (36) aligned, 
fixed bin (35)) ; 

call hcs_$get_uid_f i 1 e (di r_name, entry_name,uid, code); 

ARGUMENTS 

dir_name 

is the name of the directory containing the entry. (Input) 
entry_name 

is the name of the entry whose unique identifier is to be returned. (Input) 

uid 

is the unique identifier of the entry. (Output) 

code 

is a standard storage system status code. (Output) 
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Name: hcs $get uid___seg 

This entry point, when given a pointer to a segment, returns the unique identifier 
associated with the segment. 

USAGE 

declare hcs_$get_uid_seg entry (ptr, bit (36) aligned, fixed bin (35)); 

call hcs_$get_uid_seg (seg_ptr, unique_id, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment whose unique identifier is to be determined. (Input) 
unique_id 

is the unique identifier associated with the segment. (Output) 
is a standard storage system status code. (Output) 



Name: hcs Sget user access modes 

This entry point returns the user's effective access mode and extended access mode on 
a branch. For a description of access modes, see "Effective Access" in the Multics 
Programmer's Reference Manual, Order No. AG91. 

USAGE 

declare hcs_$get_user_access_modes entry (char (*) , char (*) , char (*) , 
fixed bin, bit (36) aligned, bit (36) aligned, fixed bin (35)); 

call hcs_$get_user_access_modes (dir_name, entryname, user_id, ring, 
mode, ex_mode, code) ; 

ARGUMENTS 

dir_name 

is the directory name of the branch. (Input) 
entryname 

is the entry name of the branch. (Input) 
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user_id 

is the access name of the user in the form Person_id.Project_id_.tag. (Input) This 
is limited to 32 characters. If null, the access name of the calling process is used. 

ring 

is the validation level that is to be used in computing effective access. (Input) It 
must be a value between 0 and 7 inclusive, or -1. If the ring value is -1, the 
default value of the validation level of the calling process is used. This default 
should be used in all cases except those in which a different ring's access is 
explicitly required. 

mode 

is the effective access mode of the user on the branch (see "Notes" below). 
(Output) 

ex_mode 

is the extended access mode of the user on the branch. (Output) 

code 

is a standard status code. (Output) 
ACCESS REQUIRED 

The user must have status permission on the containing directory, unless the access 
name supplied is that of the calling process or is null. 

NOTES 

The include file access_modes_values. incl.pll defines mnemonics for the different values 
of mode. Extended access modes are defined by the subsystem owning the branch. 

i 

Name: hcs $get user access modes ptr | 

This entry point returns the effective access mode and extended access mode of a user 
to a segment, given a pointer to the segment, the name of the user, and the 
validation level (ring number) of the user. (For a description of this mode, see 
"Effective Access" in the Mufti cs Programmer's Reference Manual, Order No. 
AG91.) 



2-433 



AG93-05 



hcs_$get_user_access_modes_ptr 



hcs_$get_user_access_modes_ptr 



| USAGE 

I declare hcs_$get_user_access_modes entry (pointer, fixed bin, bit (36) 
aligned, bit (36) aligned, fixed bin (35)); 

I call hcs_$get_user_access_modes (segment_ptr , user_id, ring, mode, 

ex_mode s code) ; 

I ARGUMENTS 
I segment_ptr 

i is a pointer to the segment for which access will be returned (Input) 
user_id 

is the access name fo the user in the form Person_id.Project_id.tag. (Input) This 
is limited to 32 characters. If null, the access name of the calling process is used. 

ring 

is the validation level that is to be used in computing effective access. (Input) It 
must be a value between 0 and 7 inclusive, or -1. If the ring value is -i, a 
default value of the validation level of the calling process is used. This default 
should be used in all cases except those in which a different ring's access is 
explicitly required. 

I mode 

! is the effective access mode of the user to the branch (see "Notes" below). 

(Output) 

I ex_mode 

1 is the extended access mode of the user to the branch. (Output) 

I code 

! is a standard status code. (Output) 

I ACCESS REQUIRED 

The user must have status permission on the containing directory, unless the access 
name supplied is that of the calling process or null. 

I NOTES 

I The include file access_modes_values.incl.pll defines mnemonics for the different values 
I of mode. Extended access modes are defined by the subsystem owning the branch. 
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Name: hcs $get user effmode 

This entry point returns a user's effective access mode on a branch. (For a 

description of access modes, see "Effective Access" in the Programmer's Reference 
Manual.) 

USAGE 

declare hcs_$get_user_ef fmode entry (char (*) , char (*) , char (*) , 
fixed bin, fixed bin(5)» fixed bin (35)); 

call hcs_$get_user_ef fmode (dir_name, entryname, user_id, ring, mode, 
code) ; 

ARGUMENTS 

dir_name 

is the directory name of the branch. (Input) 
entryname 

is the entry name of the branch. (Input) 
user_id 

is the access name of the user in the form Person_id.Project_id_.tag. (Input) This 
is limited to 32 characters. If null, the access name of the calling process is used. 

ring 

is the validation level that is to be used in computing effective access. (Input) It 
must be a value between 0 and 7 inclusive, or -1. If the ring value is =1, a 
default value of the validation level of the calling process is used. This default 
should be used in all cases except those in which a different ring's access is 
explicitly required. 

mode 

is the effective access mode of the user to the branch (see "Notes" below). 
(Output) 

code 

is a standard status code. (Output) 
NOTES 

The mode argument is a fixed binary number where the desired mode is encoded with 
one access mode specified by each bit The modes for segments are: 

read the 8-bit is 1 (i.e., 01000b) 

execute the 4-bit is 1 (i.e., 00100b) 

write the 2-bit is 1 (i.e., 00010b) 
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The modes for directories are: 



status 
modi f y 
append 



the 8-bit 
the 2-bit 
the 1-bit 



i s 
t s 
i s 



1 



(i 
(i 
(i 



e., 01000b) 
e., 00010b) 
e., 00001b) 



The unused bits are reserved for unimplemented attributes and must be 0. For 
example, rw access is 01010b in binary form, and 10 in decimal form. The 
access_mode_values. incl.pll include file defines mnemonics for these values: 



del (N_ACCESS_BIN init 

R_ACCESS_BIN init 

E_ACCESS_BIN init 

W_ACCESS_BIN init 

RW_ACCESS_BIN init 

RE_ACCESS_BIN init 

REW_ACCESS_BIN init 

S_ACCESS_BIN init 

M_ACCESS_BIN init 

A_ACCESS_BIN init 

a * r» r* I- r- n i 1 1 • „ * ju. 

3H_HUl»COO_D I IN iniL 

SM_ACCESS_BIN init 

SMA_ACCESS_BIN init 
fixed bin (5) internal 



00000b) , 
01000b) , 
00100b) , 
00010b) , 
01010b) , 
01 100b) , 
011 10b) , 

01000b) , 
00010b) , 
00001b) , 
(01001b) , 
01010b) , 
0101 lb)) 



/ '1 



static options (constant) 



The user must have status permission on the containing directory, unless the access 
name supplied is that of the calling process or null. 



Name: hes $high low seg count 

This entry point returns information about the lowest and highest segment numbers 
used in the process, excluding hardcore segments. 

USAGE 

declare hcs_$h i gh_l ow_seg_count entry (fixed bin, fixed bin); 

call hcs_$high_low_seg_count (nonhardcore_seg_count , 
lowest_nonhardcore_segno) ; 

ARGUMENTS 

nonhardcore_seg_count 

is the number of nonhardcore segment numbers being used. (Output) 
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lowest_nonhardcore_segno 

is the lowest nonhardcore segment number. (Output) 

ACCESS REQUIRED 

No access is required. 



Name: hcs_$history_regs__get 

This entry point returns the current state of the per-process history register switch. 
USAGE 

declare hcs_$h i story_regs_get entry (bit (1) aligned); 
call hcs_$h i story__regs_get (current__state) ; 
ARGUMENTS 
current_state 

is the current state of the per-process history register switch. (Output) 
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Name: hcs_$history regs__set 

This entry point controls the state of the per-process switch. If this per-process 
switch is set on OT'b), then history registers of the processor that a process was 
executing on at the time of a signalable fault (e.g., illegal_procedure) are stored by 
the fault module (fim) and copied into the signaller's stack frame (return_to_ring_0_). 
If the per-process switch is set off and the per-system switch 
(wired_hardcore_data$global_hregs) is off, then the history register block in the 
signaller's stack frame is set to all zeros. 

USAGE 

declare hcs_$h i story_regs_set entry (bit (1) aligned); 
call hcs_$hi story_regs_set (des i red_state) ; 
ARGUMENTS 
desired_state 

is the desired state of the per-process switch. (Input) 
"l"b on 
"0"b off 



Name: hcs $initiate 

TV* 4 c tvxr *%sv«*it \uUa*» miiAM o notViMAmA on/1 o r£tfAfAnr>A a fr»oVac VnAiim tl>£± 

xni& wj.ii.ij iA/iu ttiiwu giTvu a jsaii.iij.aiuw auw a xwivivuvw uaiiiw, iiidivw iwuwttu t»iiw 

segment defined by the pathname, initiates the given reference name, and increments 
the count of initiated reference names for the segment 

Use this entry point when you need to initiate a file with a nonblank (nonnull) 
reference name, and use the initiate_file_ subroutine when you need to initiate a file 
with a blank (null) reference name. 

USAGE 

declare hcs_$ i n i t i ate entry (char (*) , char (*) , char (*) , fixed bin(l), 
fixed bin (2), ptr, fixed bin (35)); 

call hcs_$ini tiate (dir_name, entryname, ref_name, seg_sw, copy_ct l_sw, 
seg ptr, code) ; 

ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment (Input) 



11/86 



2-437 



AG93-05A 



hcs_$initiate 



hcs_$initiate 



ref_name 

is the reference name. (Input) If it is zero length, the segment is initiated with a 
null reference name. 

seg_sw 

is the reserved segment switch. (Input) 

0 if no segment number has been reserved. 

1 if a segment number was reserved. 

copy_ctl_sw 

is obsolete, and should be set to zero. (Input) 
seg_ptr 

is a pointer to the segment. 
1 is seg^sw is on. (Input) 
0 is seg_sw is off. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have nonnull access on the segment (the entryname argument) in order 
to make it known. 

If a segment is concurrently initiated more than a system-defined number of times, 
the usage count of the segment is said to be in an overflowed condition, and further 
initiations do not affect the usage count. This affects the use of the hcs_$terminate_noname 
and hcs_$terminate_name entry points. If the reserved segment switch is on, then the 
segment pointer is input and the segment is made known with that segment number. 
In this case, the user supplies the initial segment number, If the reserved segment 
switch is off, a segment number is assigned and returned as a pointer. 

If entryname cannot be made known, a null pointer is returned for seg_ptr and the 
returned value of code indicates the reason for failure. Thus, the usual way to test 
whether the call was successful is to check the pointer, not the code, since the code 
may be nonzero even if the segment was successfully initiated. If entryname is already 
known to the user's process, code is returned as error_table_$segknown and the 
seg_ptr argument contains a nonnull pointer to entryname. If ref_name has already 
been initiated in the current ring, the code is returned as error_table_$namedup. The 
seg_ptr argument contains a valid pointer to the segment being initiated. If entryname 
is not already known, and no problems are encountered, seg_ptr contains a valid 
pointer and code is 0. 
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Name: hcs Sinitiate count 

The hcs_$initiate_count entry point, when given a pathname and a reference name, 
causes the segment defined by the pathname to be made known and the given 
reference name initiated. A segment number is assigned and returned as a pointer and 
the bit count of the segment is returned. • 

Use this entry point when you need to initiate a file with a nonblank (nonnull) 
reference name, and use the initiate_file_ subroutine when you need to initiate a file 
with a blank (null) reference name. 

USAGE 

declare hcs_$ i ni t i ate_count entry (char (*) f char (*) , char (*) , 
fixed bin(2l+), fixed bin (2), ptr, fixed bin (35)); 

call hcs_$ i ni t i ate_count (dir_name, entryname, ref_name, bit_count, 
copy_ct !_sw, seg_ptr, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment (Input) 
ref_name 

is the reference name. (Input) If it is zero length, the segment is initiated with a 
null reference name. 

bit_count 

is the bit count of the segment. (Output) 
copy_ctl_sw 

is obsolete, and should be set to zero. (Input) 
seg_ptr 

is a pointer to the segment (Output) 

code 

is a storage system status code. (Output) 
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NOTES 



The user must have nonnull access on the segment (the entryname argument) in order 
to make it known. 

If entryname cannot be made known, a null pointer is returned for seg_ptr and the 
returned value of code indicates the reason for failure. Thus, the usual way to test 
whether the call was successful is to check the pointer, not the code, since the code 
may be nonzero even if the segment was successfully initiated. If entryname is already 
known to the user's process, code is returned as error_table_$segknown and the 
seg_ptr argument contains a nonnull pointer to entryname. If entryname is not already 
known, and no problems are encountered, seg_ptr contains a valid pointer and code is 
0. If ref_name has already been initiated in the current ring, the code is returned as 
error_table_$namedup. The seg_ptr argument contains a valid pointer to the segment 
being initiated. If the seg^ptr argument contains a nonnull pointer, the bit_count 
argument is set to the bit count of the segment to which seg_ptr points. 



Name: hcs Sinitiate search rules 

This entry point provides the user with a subroutine interface for specifying the search 
rules that he wants to use in his process. 



declare hcs_$ini ti ate_search_rul es entry (ptr, fixed bin(35)); 
call hcs_$ini tiate_search_rules (search_rul es_ptr , code); 
ARGUMENTS 
search_rules_ptr 

is a pointer to a structure containing the new search rules. See "Information 
Structure" below. (Input) 



USAGE 



code 



is a storage system status code. (Output) 



INFORMATION STRUCTURE 



The structure pointed to by search_rules_ptr is declared as follows: 



del 1 search_rules 
2 number 
2 names 



a 1 i gned , 
fixed bin, 

(21) char (168) aligned; 
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STRUCTURE ELEMENTS 
number 

is the number of search rules contained in the array. The current maximum 
number of search rules the user can define is 21. 

names 

are the names of the search rules. Two types of search rules are permitted: 
absolute pathnames of directories to be searched or keywords. 

LIST OF KEYWORDS 



initiated_segments 

search for the already initiated segments. 

referencing_dir 

search the containing directory of the segment making the reference. 

working^dir 

search the working directory. 

process_dir 

search the process directory. 

home_dir 

search the home directory. 

set_search_directones 

insert the directories following this keyword into the default search rules after 
working_dir, and make the result the current search rules. 

site-defined keywords 

may also be specified. These keywords may expand into one or more directory 
pathnames. The keyword, default, is always defined to be the site's default search 
rules. 

NOTES 

The set_search_directories keyword, when used, must be the first search rule specified 
and the only keyword used. If this keyword is used, hcs_$initiate_search_rules sets the 
default search rules, and then inserts the specified directories in the search rules after 
the working directory. 

Some of the keywords, such as set_search_directories, are expanded into more than one 
search rule. The limit of 21 search rules applies to the final number of search rules 
to be used by the process as well as to the number of rules contained in the array. 

The search rules remain in effect until this entry point is called with a different set 
of rules or the process is terminated. 
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Codes that can be returned from this entry point are: 

error_table_$bad_string (not a pathname or keyword) 

error_table_$notadir 

error_table_$too_many_sr 

Additional codes can be returned from other procedures that are called by 
hcs_$initiate_search_rules. 

For the values of the site-defined keywords, the user may call the 
hcs_$get_system_search_rules entry point 



Name: lies Slist acl 

This entry point is used either to list the entire access control list (ACL) of a 
* segment or to return the access modes of specified ACL entries. 

USAGE 

declare hcs_$ 1 i st_ac 1 entry (char (*) , char (*) , ptr, ptr, ptr, fixed bin, 
fixed bin (35)) ; 

call hcs_$ 1 i st_ac 1 (dir_name, entryname, area_ptr, area_ret_ptr , 
acl_ptr, acl_count, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 
area_ptr 

points to an area in which the list of ACL entries, which make up the entire 
ACL of the segment, is allocated. (Input) If area_ptr is null, then the user wants 
access modes for certain ACL entries; these will be specified by the structure 
pointed to by acl_ptr (see below). 

area_ret_ptr 

points to the start of the allocated list of ACL entries. (Output) 
acl_ptr 

if area_ptr is null, then acl_ptr points to an ACL structure, segment_acl_array, 
into which mode information is placed for the access names specified in that 

j same structure. The segment_acl_array structure is discussed in the description of 

j hcs_$add_acl_entries. (Input) 
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acl_count 

is the number of entries in the ACL structure. (Input or Output) 
Input 

is the number of entries in the ACL structure identified by acl_ptr. 
Output 

is the number of entries in the segment_acl_array structure allocated in the 
area pointed to by area_ptr, if area_ptr is not null. 

code 

is a storage system status code. (Output) 
NOTES 

If acl_ptr is used to obtain modes for specified access names (rather than for all 
access names on a segment), then each ACL entry in the segment_acl_array structure 
either has status_code set to 0 and contains the segment's mode or has status_code set 
to error_table_$user_not_found and contains a mode of 0. 



Name: hcs $list dir acl 

This entry point is used either to list the entire access control list (ACL) of a 
directory or to return the access modes for specified entries. 

USAGE 

1 ara ^ 1 I «» +• Air eir\ + v\t ( r^Wrtr- -» i» (ft\ r\+»» ir\1- r r\-t- »• 

viww i s*i w nv»_y i i ~ i i _«^» ■ wn 1. 1 j \wilSl \ i » Vllfli \-/ » K ' 1 K *•' * 

fixed bin, fixed bin(35))» 

call hcs_$l i st_di r_acl (dir_name, entryname, area_ptr, area_ret_ptr , 
acl_ptr, acl__count, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
area_ptr 

points to an area in which the list of ACL entries, which make up the entire 
ACL of the directory, is allocated. (Input) If area_ptr is null, then the user 
wants access modes for certain ACL entries; these will be specified by the 
structure pointed to by acl_ptr (see below). 

area_ret_ptr 

points to the start of the allocated list of ACL entries. (Output) 
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acl_ptr 

if area_ptr is null, then acl_ptr points to an ACL structure, dir_acl_array, into 
which mode information is placed for the access names specified in that same 
structure. The dir_acl_array structure is discussed in the description of 
hcs_$add_dir_acl_entries. (Input) 

acl_count 

is the number of entries in the ACL structure. (Input or Output) 
Input 

is the number of entries in the ACL structure identified by acl_ptr. 
Output 

is the number of entries in the dir_acl_array structure allocated in the area 
pointed to by area_ptr, if area_ptr is not null. 

code 

is a storage system status code. (Output) 
NOTES 

If acl_ptr is used to obtain modes for specified access names (rather than for all 

ovvcda named un a uiicwlui^/, uicn cawi n^i^ ciiuj m uic uijL_avi_eu laj auuv/iuic 

either has status_code set to 0 and contains the mode of the directory or has 
status_code set to error_table_$user_not_found and contains a mode of 0. 



Name: hcs $list dir inacl 

This entry point is used either to list the entire initial access control list (initial ACL) 
for new directories created for the specified ring within the specified directory or to 
* return the access modes for specified initial ACL entries. 

USAGE 

declare hcs_$ 1 i st_d i r_i nac 1 entry (char (*) , char (*) , ptr, ptr, ptr, 
fixed bin, fixed bin (3), fixed bin (35)); 

call hcs_$l ist_di r__ inacl (dir_name, entryname, area_ptr, area_ret_ptr , 
acl_ptr, acl_count, ring, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the directory. (Input) 
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area_ptr 

points to an area into which the list of initial ACL entries, which makes up the 
entire initial ACL of the directory, is allocated. (Input) If area_ptr is null, then 
the user wants access modes for certain initial ACL entries; these will be specified 
by the structure pointed to by acl_ptr (see below). 

area_ret_ptr 

points to the start of the allocated list of initial ACL entries. (Output) 
acl_ptr 

if area_ptr is null, then acl_ptr points to an initial ACL structure, dir_acl_array, 
into which mode information is placed for the access names specified in that 
same structure. The dir_acl_array structure is discussed in the description of 
hcs_$add_dir_inacl_entries. (Input) 

acl_count 

is the number of entries in the ACL structure. (Input or Output) 
Input 

is the number of entries in the initial ACL structure identified by 
acl_ptr. 

Output 

is the number of entries in the dir_acl_array structure allocated in the 
area pointed to by area_ptr, if area_ptr is not null. 

ring 

is the ring number of the initial ACL. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

If acl_ptr is used to obtain modes for specified access names (rather than obtaining 
modes for all access names on the initial ACL), then each initial ACL entry in the 
dir_acl_array structure either has status_code set to 0 and contains the directory's 
mode or has status_code set to error_table_$user_not_found and contains a mode of 0. 
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Name: hcs $list inacl 

This entry point is used either to list the entire initial access control list (initial ACL) 
for new segments created for the specified ring within the specified directory or to 
* return the access modes for specified initial ACL entries. 

USAGE 

declare hcs_$ li st_i nacl entry (char (*) , char (*) , ptr, ptr, ptr, 
fixed bin, fixed bin (3), fixed bin(35))> 

call hcs_$ li st_i nacl (dir_name, entryname, area_ptr, area_ret_ptr , 
acl_ptr, acl_count, ring, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
area_ptr 

points to an area into which the list of initial ACL entries, which makes up the 
entire initial ACL of the directory, is allocated. (Input) If area_ptr is null, then 
the user wants access modes for certain initial ACL entries; these will be specified 
by the structure pointed to by acl_ptr (see below). 

area_ret_ptr 

points to the start of the allocated list of initial ACL entries. (Output) 
acl_ptr 

if area_ptr is null, then acl_ptr points to an initial ACL structure, segment_acl_array, 
into which mode information is to be placed for the access names specified in 
that same structure. The segment_acl_array structure is discussed in the description 
of hcs_$add_inacl_entries. (Input) 

acl_count 

is the number of entries in the initial ACL structure. (Input or Output) 
Input 

is the number of entries in the initial ACL structure identified by acl_ptr. 
Output 

is the number of entries in the segment_acl_array structure allocated in the 
area pointed to by area_ptr, if area_ptr is not null. 

ring 

is the ring number of the initial ACL. (Input) 

code 

is a storage system status code. (Output) 
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NOTES 

If acl_ptr is used to obtain modes for specified access names (rather than obtaining 
modes for all access names on the initial ACL), then each initial ACL entry in the 
segment_acl_array structure either has status_code set to 0 and contains the segment's 
mode or has status_code set to error_table_$user_not_found and contains a mode of 0. 



Name: hcs__$lv attached 

This entry point checks to see if a logical volume is attached and available for use in 
this process. 

USAGE 

del hcs_$ 1 v_attached entry (bit (36) aligned) returns (fixed bin (35))* 

code = hcs_$ 1 v_attached (lvid) ; 

ARGUMENTS 

lvid 

is the logical volume id. Use mdc_$find_lvid to get the logical volume identifier 
for a given logical volume name. (Input) 

code 

is a standard system status code. (Output) Its possible values are: 
0 

the volume is attached and available for use. 

error_table_$logical_volume_not_connected 

the volume is private and has not been attached in this process. 

error_table_$logical_volume_not_defined 

the volume specified by lvid is not known to the system. 

ACCESS REQUIRED 

No access is required. 
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Name: hcs_$make entry 

This entry point, when given a reference name and an entry point name, returns the 
value of a specified entry point If the reference name has not yet been initiated, the 
search rules are used to find a segment or multisegment file (MSF) with a name the 
same as the reference name. The file is made known and the reference name 
initiated. Use hcs_$make_ptr to have a pointer returned. 

USAGE 

declare hcs_$make_entry entry (ptr, char (*) , char (*) , entry, 
fixed bin (35)) ; 

call hcs_$make_entry (ref_ptr, entryname, entry_poi nt_name, entry_point, 
code) ; 

ARGUMENTS 

ref_ptr 

is a pointer to the segment that is considered the referencing procedure (see 
"Notes" below). (Input) 

entryname 

is the entryname or reference name of the file. (Input) 

entry _point_name 

is the name of the entry point to be located. (Input) 

entry_point 

is the value of the segment entry point specified by entryname and entry_point_name. 
(Output) 

code 

is a storage system . status code. (Output) 
NOTES 

The directory in which the segment pointed to by ref_ptr is located is used as the 
referencing directory for the standard search rules. If ref_ptr is null, then the 
standard search rule specifying the referencing directory is skipped. Search rules are 
described in the Programmer's Reference Manual. Normally ref_ptr is null. If the 
segment pointed to by ref_ptr is a component of an object MSF, the directory used 
as the referencing dir is the directory containing the MSF, rather than the MSF itself. 

The entryname and entry_point_name arguments are nonvarying character strings with a 
length of up to 32 characters. They need not be aligned and can be blank padded. 
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If a null string is given for the entry_point_name argument, then an entry value 
referring to the base of the segment is returned. In any case, the segment or MSF 
identified by entryname is made known to the process with the entryname argument 
initiated as a reference name. If an error is encountered upon return, the 
entry_point_ptr argument is null and an error code is given. 



Name: hcs__$make ptr 

This entry point, when given a reference name and an entry point name, returns a 
pointer to a specified entry point. If the reference name has not yet been initiated, 
the search rules are used to find a segment or multisegment file (MSF) with a name 
the same as the reference name. The file is made known and the reference name 
initiated. Use hcs_$make_entry to have entry values returned. 

USAGE 

declare hcs_$make_ptr entry (ptr, char (*) , char (*) , ptr, fixed bin(35))» 

call hcs_$make_ptr (ref_ptr, entryname, entry_poi nt_name, 
entry_poi nt_ptr , code); 

ARGUMENTS 

ref_ptr 

is a pointer to the segment that is considered the referencing procedure. (Input) 
See "Notes" below. 

entryname 

is the entryname of the file. (Input) 

entry_point_name 

is the name of the entry point to be located. (Input) 

entry_point_ptr 

is the pointer to the segment entry point specified by entryname and entry_point_name. 
(Output) 

code 

is a storage system status code. (Output) 
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NOTES 

The directory in which the segment pointed to by ref_ptr is located is used as the 
referencing directory for the standard search rules. If ref_ptr is null, then the 
standard search rule specifying the referencing directory is skipped. For a discussion 
of standard search rules, refer to the Programmer's Reference Manual. Normally 
I ref_ptr is null. If the segment pointed to by ref_ptr is a component of an object 
MSF, the directory used as the referencing dir is the directory containing the MSF, 
rather than the MSF itself. 

The entryname and entry _point_name arguments are nonvarying character strings with a 
length of up to 32 characters. They need not be aligned and can be blank padded. If 
a null string is given for the entry_point_name argument, then a pointer to the base 
j of the segment is returned. In any case, the segment or MSF identified by entryname 
is made known to the process with the entryname argument initiated as a reference 
name. If an error is encountered upon return, the entry_point_ptr argument is null 
and an error code is given. 



Name: hcs Smake seg 

This entry point creates a segment with a specified entryname in a specified directory. 
Once the segment is created, it is made known to the process and a pointer to the 
segment is returned to the caller. If the segment already exists or is already known, a 
nonzero code is returned; however, a pointer to the segment is still returned. 

USAGE 

declare hcs_$make_seg entry (char (*) , char (*) , char (*) , fixed bin(5)» 
ptr , f i xed b i n (35) ) ? 

call hcs_$make_seg (dir_name, entryname, ref_name, mode, seg_ptr, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 
ref_name 

is the desired reference name or a null character string (""). (Input) 
mode 

specifies the mode for this user, (Input) See "Notes" in the description of 
hcs_$append_branchx for more information on modes. 
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seg_ptr 

is a pointer to the created segment. (Output) 

code 

is a storage system status code. (Output) It may be one of the following: 
error_table_$namedup 

if the specified segment already exists or the specified reference name has 

already been initiated. 
error_table_$segknown 

if the specified segment is already known. 

NOTES 

If dir_name is null, the process directory is used. If the entryname is null, a unique 
name is generated. The segment is made known and the reference name, ref_name, is 
initiated. 

If the segment cannot be created or made known, a null pointer is returned for 
seg_ptr and the returned value of code indicates the reason for failure. Thus, the 
usual way to test whether the call was successful is to check the pointer, not the 
code, since the code may be nonzero even if the segment was successfully initiated. 



Name: hcs Squota move 

This entry point moves all or part of a quota between two directories, one of which 
is immediately inferior to the other. 

USAGE 

declare hcs__$quota_move entry (char (*) , char (*) , fixed bin(l8), 
fixed bin(35)) ; 

call hcs_$quota__move (dir__name, entryname, quota_change, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
quota_change 

is the number of records of secondary storage quota to be moved between the 
superior directory and the inferior directory. (Input) (See "Notes" below.) 
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code 

is a storage system status code. (Output) 
NOTES 

The entryname specified by the entryname argument must be a directory. 
The user must have modify permission on both directories. 

After the quota change, the remaining quota in each directory must be greater than 
the number of records used in that directory. 

The quota_change argument can be either a positive or negative number. If it is 
positive, the quota is moved from dir_name to entryname. If it is negative, the move 
is from entryname to dir_name. If the change results in zero quota left on 
entryname, that directory is assumed to no longer contain a terminal quota and all of 
its used records are reflected up to the used records on dir_name. It is a restriction 
that no quota in any of the directories superior to entryname can be modified from a 
nonzero value to a zero value by this subroutine. 



Name: hcs Squota read 

This entry point returns the segment record quota and accounting information for a 
directory. 

USAGE 

declare hcs_$quota_read entry (char (*) , fixed bin(l8), fixed bin (71), 
bit (36) aligned, bit (36), fixed bin(l), fixed bin(l8), 
fixed bin (35)) ; 

call hcs_$quota_read (dir_name, quota, trp, tup, sons_lvid, tacc_sw, 
used, code) ; 

ARGUMENTS 

dir_name 

is the pathname of the directory for which quota information is desired. (Input) 
quota 

is the segment record quota in the directory. (Output) 

trp 

is the time-record product (trp) charged to the directory. (Output) This 
double-precision number is in units of record-seconds. 
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tup 

is the time, expressed in storage system time format (the high-order 36 bits of 
the 52-bit time returned by the clock_ subroutine), that the trp was last updated. 
(Output) 

sons_lvid 

is the logical volume ID for segments contained in this directory. (Output) 
tacc_sw 

is the terminal account switch. (Output) The setting of this switch determines how 
charges are made. 

1 records are charged against the quota in this directory 

0 records are charged against the quota in the first superior directory with a 
terminal account 

used 

is the number of records used by segments in this directory and by segments in 
nonterminal inferior directories. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

If the directory contains a nonterminal account, the quota, trp, and tup are all zero. 
The variable specified by used, however, is kept up-to-date and represents the number 
of records in this directory and inferior, nonterminal directories. 



Name: hcs_Srelease segment numbers 

This entry point releases reserved segment numbers which are not associated with 
segments. 

USAGE 

declare hcs_$rel ease_segment_numbers entry (fixed bin, fixed bin, 
fixed bin (35)) J 

call hcs_$rel ease_segment_numbers (f i rst_segno, block_size, code); 
ARGUMENTS 

first_segno 

is the first segment number of the reserved block. (Input) 
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block_size 

is the number of segment numbers to be released. (Input) 

code 

is error_table_$invalidsegno if any portion of the segment number range is an 
invalid segment number. It is error_table_$segknown if any of the segment 
numbers is known. (Output) 

NOTES 

This entry should be used in the cleanup handler of programs which reserve segment 
number blocks using hcs_$reserve_segment_numbers. If code is non-zero, no segment 
numbers were released. For example, suppose that a program reserves a block of ten 
segment numbers and a cleanup condition occurs after only four of these segment 
numbers have been used in calls to hcs_$initiate. The cleanup handler should call 
hcs_$release_segment_numbers for the last six segments of the block and then 
individually terminate the first four segments. 



Name: hcs Sreplace acl 

This entry point replaces an entire access control list (ACL) for a segment with a 
user-provided ACL, and can optionally add an entry for *.SysDaemon.* with mode rw 
to the new ACL. The segment_acl_array structure described in hcs_$add_acl_entries is 
used by this entry point. 

USAGE 

declare hcs_$repl ace_acl entry (char (*) , char (*) , ptr, fixed bin, 
bit (1) , fixed bin(35)) 5 

call hcs_$repl ace_acl (dir_name, entryname, acl_ptr, acl_count, 
no_sysdaemon__sw, code) ; 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 
acl_ptr 

points to the user supplied segment_acl_array structure that is to replace the 
current ACL. (Input) 

acl_count 

is the number of entries in the segment_acl_array structure. (Input) 
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no_sysdaemon_sw 

is a switch that indicates whether an rw *.SysDaemon.* entry is to be put on the 
ACL of the segment after the existing ACL has been deleted and before the 
user-supplied segment_acl_array entries are added. (Input) 
"0"b adds rw *.SysDaemon.* to ACL. 

"l"b replaces the existing ACL with only the user-supplied segment_acl_array. 

code 

is a storage system status code. (Output) 
NOTES 

If acl_count is zero, then the existing ACL is deleted and only the action indicated (if 
any) by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, 
processing of the segment_acl_array entries is performed top to bottom, allowing later 
entries to overwrite previous ones if the access_name in the segment_acl_array 
structure is identical. 

If the segment is a gate and if the validation level is greater than ring 1, access is 
restricted to the same project as that of the user or to the SysDaemon project. If the 
replacement ACL is in error, then no processing is performed and the subroutine 
returns the code error_table_$invalid_project_for_gate. 



Name: hcs Sreplace dir acl 

This entry point replaces an entire access control list (ACL) for a directory with a 
user-provided ACL, and can optionally add an entry for *. SysDaemon.* with mode 
sma to the new ACL. The dir_acl_array structure described in hcs_$add_dir_acl_entries 
is used by this entry point. 

USAGE 

declare hcs_$repl ace_d i r_acl entry (char (*) , char (*) , ptr, fixed bin, 
bi t (1) , fixed bin (35)) ; 

call hcs_$repl ace_d i r_acl (dir_name, entryname, acl_ptr, acl_count, 
no_sysdaemon_sw, code) : 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the directory. (Input) 
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aci_ptr 

points to a user-supplied dir_acl_array structure that is to replace the current 
ACL. (Input) 

acl_count 

contains the number of entries in the dir_acl_array structure. (Input) 
no_sysdaemon_sw 

is a switch that indicates whether the sma *.SysDaemon.* entry is put on the 
ACL of the directory after the existing ACL of the directory has been deleted 
and before the user-supplied dir_acl_array entries are added. (Input) 
"0"b adds sma *.SysDaemon.* to ACL. 

"l"b replaces the existing ACL with only the user-supplied dir_acl_array. 

code 

is a storage system status code. (Output) 
NOTES 

If acl_count is zero, then the existing ACL is deleted and only the action indicated (if 
any) by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, 
processing of the dir_acl_array entries is performed top to bottom, allowing later 
entries to overwrite previous ones if the access_name in the dir_acl_array structure is 
identical. 

If the replacement ACL is in error, no processing is performed for that ACL entry in 
the dir_acl_array structure and the subroutine returns the code error_table_$bad_name 
or error_table_$invalid_ascii, whichever is appropriate. 



Name: hcs $replace dir inacl 

This entry point replaces an entire initial access control list (initial ACL) for new 
directories created for the specified ring within a specified directory with a 
user-provided initial ACL, and can optionally add an entry for *.SysDaemon.* with 
mode sma to the new initial ACL. The dir_acl_array structure described in the 
hcs_$add_dir_acl_entries entry point is used by this entry point. 

USAGE 

declare hcs_$repl ace_d i r_inacl entry (char (*) , char (*) , ptr, fixed bin, 
bit(l), fixed bin(3), fixed bin(35)); 

call hcs_$replace_di r_i nacl (dir_name, entryname, acl_ptr, acl_count, 
no_sysdaemon_sw, ring, code); 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
acl_ptr 

points to a user-supplied dir_acl_array structure that is to replace the current 
initial ACL. (Input) 

acl_count 

contains the number of entries in the dir_acl_array structure. (Input) 
no_sysdaemon_sw 

is a switch that indicates whether the sma *.SysDaemon.* entry is put on the 
initial ACL after the existing initial ACL is deleted and before the user-supplied 
dir_acl_array entries are added. (Input) 
"0"b adds sma *.SysDaemon.* entry 

'T'b replaces the existing initial ACL with only the user-supplied dir_acl_array 

ring 

is the ring number of the initial ACL. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

If acl_count is zero, then the existing initial ACL is deleted and only the action 
indicated (if any) by the no_sysdaemon_sw switch is performed. If acl_count is 
greater than zero, processing of the dir_acl_array entries is performed top to bottom, 
allowing later entries to overwrite previous ones if the access_name in the 
dir_acl_array structure is identical. 



Name: hcs $replace inacl 

This entry point replaces an entire initial access control list (initial ACL) for new 
segments created for the specified ring within a specified directory with a 
user-provided initial ACL, and can optionally add an entry for *.SysDaemon.* with 
mode rw to the new initial ACL. The segment_acl_array structure described in the 
hcs_$add_acl_entries entry point is used by this entry point. 
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USAGE 

declare hcs_$repl ace_i nacl entry (char (*) , char (*) , ptr, fixed bin, 
bit (1) , fixed bin (3), fixed bin (35)); 

call hcs_$repl ace_i nacl (di rename, entryname, acl_ptr, acl_count, 
no_sysdaemon_sw, ring, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 
acl_ptr 

points to the user-supplied segment_acl_array structure that is to replace the 
current initial ACL. (Input) 

acl_count 

contains the number of entries in the segment_acl_array structure. (Input) 
no_sysdaemon_sw 

is a switch that indicates whether the rw *.SysDaemon.* entry is to be put on the 
initial ACL after the existing initial ACL is deleted and before the user-supplied 
segment_acl_array entries are added. (Input) 
"0"b adds rw *.SysDaemon.* entry 

"l"b replaces the existing initial ACL with only the user-supplied segment_acl_array 

ring 

is the ring number of the initial ACL. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

If acl_count is zero, then the existing initial ACL is deleted and only the action 
indicated (if any) by the no_sysdaemon_sw switch is performed. If acl_count is 
greater than zero, processing of the segment_acl_array entries is performed top to 
bottom, allowing later entries to overwrite previous ones if the access_name in the 
segment_acl_array structure is identical. 
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Name: hcs Sreserve segment_numbers 

This entry point allows a user to reserve a block of contiguous segment numbers. 
USAGE 

declare hcs_$reserve segment_numbers entry (fixed bin, fixed bin, 
fixed bin (35)) ; 

call hcs_$reserve_segment_numbers (block_size, first_segno, code); 

ARGUMENTS 

block_size 

is the number of segments in the segment number group. (Input) 
first_segno 

is the number of the first segment in the group assigned. (Output) 

code 

is 0 if the allocation succeeded. It is error_table_$nrmkst if there is no group of 
block_size contiguous segment numbers available. (Output) 

NOTES 

This entry removes the contiguous segment number group from the available free 
segment numbers. The assigned segment numbers are available only by using 
hcs_$initiate and specifying a reserved segment number. See also the description of 
hcs_$release_segment_numbers. 



Name: hcs Sreset ips mask 

This entry point replaces the entire ips mask with a specified mask, and returns the 
previous value of the mask with a control bit of "0"b. It can be used at the end of 
a critical section of code to restore the mask to its former value. See "Notes" in the 
description of the create_ips_mask_ subroutine for a discussion of the control bit. 

USAGE 

declare hcs_$reset_i ps_mask entry (bit (36) aligned, bit (36) aligned); 
call hcs_$reset_i ps_mask (mask, oldjnask) ; 
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ARGUMENTS 
mask 

is the new ips mask, to replace the current one. (Input) A "1" bit in a mask 
position enables the corresponding ips interrupt. 

old_mask 

is the former value of the ips mask, with a control bit of "0"b. (Output) 
NOTES 

The create_ips_mask_ subroutine can be used to create a mask, given a set of ips 
names. 

This entry point can be used at the end of a critical section of code to undo the 
mask changes made by the hcs_$set_ips_mask entry point. The old_mask returned by 
the latter entry point should be used as the value of the new mask set by this entry 
point. 



Name: hcs $set 256K switch 

This entry point sets the per-process switch which controls whether or not segments of 
maximum length 256K (262144 words) can be used. The standard maximum length for 
a segment, defined as sys_info$max_seg_size, is 255K (261120 words). The only 
supported use of 256K segments is for Fortran Very Large Arrays. 

USAGE 

declare hcs_$set_256K_swi tch entry (bit (2) aligned, bit (2) aligned, 
fixed bin (35) ) ; 

call hcs_$set_256K_swi tch (new_switch, old_switch, code); 

ARGUMENTS 

new_switch 

is the new control value. (Input) If it is "ll"b, the process may use segments 
having a maximum length of 256K words. It it is "10"b, the process may not use 
segments having a maximum length larger than sys_info$max_seg_size (255K 
words). 

old_switch 

is the previous control value. (Output) It is always set, even if an error occurs. 
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code 

is 0 if the operation was successful. It is error_table_$action_not_performed if 

new_switch was neither "ll"b or "10"b or if the callers validation level is greater 
than the process initial ring. 

NOTES 

The following code sequence provides correct resetting of the switch by a cleanup 
handler. 

del old_switch bit (2) aligned; 
del cleanup condition 

old_switch = ""b; /*invlaid switch"/ 

on cleanup begin; 

call hcs_$set_256K_swi ten (ol d_swi ten , ( M "b) , i gnore_code) ; 
end; 

call_hcs_$set_256K_swi tch ("ll"b, old_switch, code), 

/^enable big segments"/ 



Name: hes $set be 

This entry point sets the bit count of a specified segment. It also sets the bit count 
author of that segment to be the user who called it. 

USAGE 

declare hcs_$set_bc entry (char (*) , char (") , fixed bin (24), 
fixed bin (35)) ; 

call hcs_$set_bc (dir_name, entryname, bit_count, code); 

ARGUMENTS 

dirjname 

is the pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment. (Input) 
bit_count 

is the new bit count of the segment. (Input) 

code 

is a storage system status code. (Output) 
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NOTES 

The user must have write access on the segment, but does not need modify permission 
on the containing directory. 

The hcs_$set_bc_seg entry point performs the same function, when a pointer to the 
segment is provided instead of the pathname. 



Name: hcs_ $set dir ring__brackets 

This entry point, given the pathname of the containing directory and the entryname of 
the subdirectory, sets the subdirectory's ring brackets. 

USAGE 

declare hcs_$set_d i r_r i ng_brackets entry (char (*) , char (*) , 
(2) fixed bin (3), fixed bin (35)); 

call hcs_$set_d i r_r i ng_brackets (dir__name, entryname, drb, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory; (Input) 
entryname 

is the entryname of the subdirectory. (Input) 

drb 

is a two-element array specifying the ring brackets of the directory. (Input) The 
first element contains the level required for modify and append permission; the 
second element contains the level required for status permission. 

code 

is a storage system status code. (Output) 
NOTES 

The user must have modify permission on the containing directory. Also, the 
validation level must be less than or equal to both the present value of the first ring 
bracket and the new value of the first ring bracket that the user wishes set. 

Ring brackets and validation levels are discussed in "Intraprocess Access Control" in 
the Programmer's Reference Manual. 
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I Name: hcs $set dnzp sw 

| This entry point allows the dnzp switch associated with the specified segment to be 
changed. The "don't null zero pages" (dnzp) switch indicates how zero pages of a 
segment are written to disk. 

USAGE 

declare hcs_$set_dnzp_sw entry (char (*) , char (*) , bit(l), 
fixed bin (35)) 5 

call hcs_$set_dnzp_sw (dir_name, entryname, dnzp_sw, code); 

ARGUMENTS 

dir_name 

is the pathname of the directory containing the segment. (Input) 
entryname 

is the entryname of the segment. (Input) 
dnzp_sw 

is the new value of the dnzp switch. (Input) Its possible values are: 

"0"b zero pages are nulled and not written to disk or charged against quota 

"l"b zero pages are written to disk and charged against quota 

code 

is a standard system status code. (Output) Its possible values are: 

error_table_$bad_ring_brackets 

the ring brackets of the segment are less than the validation level of the 
user. 

ACCESS REQUIRED 

The user must have status and modify permission on the containing directory and w 
effective access to the segment. 
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Name: hcs $set dnzp sw seg 

This entry point allows the dnzp switch associated with the specified segment to be 
changed. The "don't null zero pages" (dnzp) switch indicates how zero pages of a 
segment are written to disk. 

USAGE 

declare hcs_$set_dnzp_sw_seg entry (ptr, bit(l), fixed bin (35)) J 
call hcs_$set_dnzp_sw_seg (seg_ptr, dnzp_sw, code); 
ARGUMENTS 
seg_ptr 

is a pointer to the segment whose dnzp switch is to be modified. (Input) 
dnzp_sw 

is the new value of the dnzp switch. (Input) Its possible values are: 

"0"b zero pages are nulled and not written to disk or charged against quota 

'T'b zero pages are written to disk and charged against quota 

code 

is a standard system status code. (Output) Its possible values are: 

error_table_$bad_ring_brackets 

the ring brackets of the segment are less than the validation level of the user. 

ACCESS REQUIRED 

The user must have status and modify permission on the containing directory and w 
effective access to the segment. 



Name: hcs $set entry bound 

This entry point, given a directory name and an entryname, sets the entry point bound 
of a segment. 

The entry point bound attribute provides a way of limiting which locations of a 
segment may be targets of a call. This entry point allows the caller to enable or 
disable a hardware check of calls to a given segment from other segments. If the 
mechanism is enabled, all calls to the segment must be made to an entry point whose 
offset is less than the entry point bound. 

In practice, this attribute is most effective when all of the entry points are located at 
the base of the segment. In this case, the entry point bound is the number of 
callable words. 
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USAGE 

declare hcs_$set_entry_bound entry (char (*) , char (*) , fixed bin (14), 
fixed bin(35)) ; 

call hcs_$set_entry_bound (dir_name, entryname, entry_bound, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 
entry_bound 

is the new value in words for the entry point bound of the segment. (Input) If 
the value of entry_bound is 0, then the mechanism is disabled. 

code 

is a storage system status code. (Output) (See "Notes" below.) 
NOTES 

A directory cannot have its entry point bound changed. 

The user must have modify permission on the containing directory. 

If an attempt is made to set the entry point bound of a segment greater than the 
system maximum of 16383, code is set to error_table_$argerr. 

The hcs_$set_entry_bound_seg entry point can be used when a pointer to the segment 
is given, rather than a pathname. 
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Name: hcs_$set__entry bound seg 

This entry point, given a pointer to a segment, sets the entry point bound of the 
segment. 

The entry point bound attribute provides a way of limiting which locations of a 
segment may be targets of a call. This entry point allows the caller to enable or 
disable a hardware check of calls to a given segment from other segments. If the 
mechanism is enabled, all calls to the segment must be made to an entry point whose 
offset is less than the entry point bound. 

In practice, this attribute is most effective when all of the entry points are located at 
the base of the segment. In this case, the entry point bound is the number of 
callable words. 

USAGE 

declare hcs_$set_entry_bound_seg entry (ptr, fixed b i n ( 1 4) , 
f i xed bin (35) ) ; 

call hcs_$set_entry_bound_.seg (seg_ptr, entry_bound, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment whose entry point bound is to be changed. (Input) 

wiiLi jr UVJUiiU 

is the new value in words for the entry point bound of the segment. (Input) If 
the value of entry_bound is 0, then the mechanism is disabled. 

code 

is a storage system status code. (Output) (See "Notes" below.) 
NOTES 

A directory cannot have its entry point bound changed. 

The user must have modify permission on the containing directory. 

If an attempt is made to set the entry point bound of a segment to greater than the 
system maximum of 16383, code is set to error_table„$argerr. 

The hcs_$set_entry_bound entry point can be used when a pathname of the segment is 
given, rather than a pointer. 
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Name: hcs $set exponent control 

This entry point changes the current settings of the flags that control the system's 
handling of exponent overflow and underflow conditions. For more information on 
exponent control see "Notes". 

USAGE 

declare hcs_$set_exponent_control entry (bit(l) aligned, bit(l) aligned, 
float bin (63), fixed bin (35)); 

call hcs_$set_exponent_control (restart_underf low, restar t_overf 1 ow, 
overf low_value, code); 

ARGUMENTS 

restart_underflow 

is "l"b if underflows should be automatically restarted, and "0"b otherwise. 
(Input) 

restart_overflow 

is 'T'b if overflows should be automatically restarted, and "0"b otherwise. (Input) 
overflow_value 

is the value used for the result of the computation in the case of overflow. 
(Input) 

code 

is a standard status code. (Output) 
NOTES 

When either of the two flags are set to zero, the corresponding error condition causes 
the appropriate fault condition to be signalled. If a flag is set to one, then the 
computation resulting in the error is automatically restarted. In the case of underflow 
its result is set to zero. In the case of positive overflow, its value is set to the value 
specified in overf low_value. In the case of negative overflow, the negative of 
overf low_value is used. The default value is the largest represen table positive number, 
available as Default_exponent_control_overflow_value in the include file 
exponent_control.incl.pll. 

This subroutine affects only the system's handling of exponent overflow and underflow 
when the overflow condition or the underflow condition is raised. In certain cases, the 
error condition is raised instead; this subroutine does not affect the system's handling 
of such cases. 

In programs not written in PL/ 1, the exponent_control_ subroutine should be used in 
place of hcs_$set_exponent_control. 
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Name: hcs $set ips mask 

This entry point replaces the entire ips mask with a supplied value, and returns the 
previous value of the mask with a control bit of "l"b. It can be used at the 
beginning of a critical section of code, to disable one or more ips interrupts, and turn 
on the control bit to indicate that some interrupts are disabled. See "Notes" below. 

USAGE 

declare hcs_$set_i ps_mask entry (bit (36) aligned, bit (36) aligned); 

call hcs_$set_i ps_mask (mask, old_mask) ; 

ARGUMENTS 

mask 

is the new value to replace the ips mask. (Input) A "1" bit in each mask position 
enables the corresponding ips interrupt. 

old_mask 

is the former value of the ips mask, with a control bit of "l"b. (Output) 
NOTES 

The IPS mask is a 36 bit quantity, 35 of the bits represent individual signals. The 
36'th bit is the control bit, used to indicate the fact that the mask has been changed 
fro its "normal" value. hcs_$set_ips_mask returns an old_mask with the 36'th bit ON. 
hcs_$reset_ips_mask returns with the 36'th bit set OFF. 

Masked IPS signals can have a serious effect on the behavior of a process. Therefore, 
it is important to have a reliable clean_up handler and any_other handler in effect 
while IPS signals are masked, to make sure that they are unmasked before the 
program returns to command level. 

The handlers should obey the convention in the following piece of code, the 
important steps of the algorithm are as follows: 

1) Clear the saved_mask. 

2) Establish the handlers. 

3) Mask IPS signals with hcs_$set_ips_mask. 

4) Perform the critical operations. 

5) Call hcs_$reset_ips_mask ONLY if the 35'th bit of the saved_mask is "l"b. 

6) Revert the handlers. 
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This protocol insures that the handlers will never call hcs_$reset_ips_mask when 
hcs_$set_ips_mask has not been called, or fail to call it when hcs_$set_ips_mask has 
been called. 



savedjnask = (36)"0"b; /* clear saved mask so 36 1 th bit is off */ 

on cleanup call clean_up; 

on any_other call f i x_up_and_cont i nue; 

call hcs_$set_i ps_mask (MASK, saved_mask) ; 

call D0_PR0TECTED_C0DE; 

call hcs_$reset_i ps_mask (saved_mask, savedjnask) ; 
revert any_other, cleanup; 

clean_up: procedure; 

if substr (savedjnask, 3&» 1) then call hcs_$reset_i ps_mask (saved_mask, 
savedjnask) ; 

/* clean things up */ 

return; 

end clean_up; 

f i x_up_and_cont i nue: procedure; 

if substr (saved_mask , 3&> 1) then call hcs_$reset_i ps_mask (saved_mask, 
saved_mask) ; 

/" close down critical operations */ 

call conti nue_to_s i gnal_ (0); 
end f i x_up_and_cont i nue; 



Name: hcs Sset max length 

This entry point, given a pathname, sets the maximum length (in words) of a segment. 
USAGE 

declare hcs_$set_max_l ength entry (char (*) , char (*) , fixed b i n ( 1 9) » 
fixed bin (35)) ; 

call hcs_$set_max_l ength (dir_name, entryname, max_length, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 
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max_length 

is the new value in words for the maximum length of the segment. (Input) 

code 

is a storage system status code. (Output) (See "Notes" below.) 
NOTES 

A directory cannot have its maximum length changed. 

The user must have modify permission on the containing directory. 

The maximum length of a segment is accurate to units of 1024 words, and if 
maxjength is not a multiple of 1024 words, it is set to the next multiple of 1024 
words. 

If an attempt is made to set the maximum length of a segment to greater than the 
system maximum, sys_info$max_seg_size. code is set to error_table_$argerr. The 
sys_info data base is described in the Programmer's Reference Manual. It is possible 
to set a segment maximum length as high as sys_info$seg_size_256K, but this is 
intended for Fortran only. General system support is still restricted to segments of 
length sys_info$max_seg_size 

If an attempt is made to set the maximum length of a segment to less than its 
current length, code is set to error_table_$invalid_max_length. 

The hcs_$set_max_length_seg entry point can be used when the pointer to the segment 
is given, rather than a pathname. 



Name: hcs_Sset max__length seg 

This entry point, given the pointer to the segment, sets the maximum length (in 
words) of a segment. 

USAGE 

declare hcs_$set_max_l ength_seg entry (ptr, fixed b i n (1 9) , 
fixed bin (35) ) 5 

call hcs_$set_max_l ength_seg (seg_ptr, max_length, code); 
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ARGUMENTS 
seg_ptr 

is the pointer to the segment whose maximum length is to be changed. (Input) 
max_length 

is the new value in words for the maximum length of the segment. (Input) 

code 

is a storage system status code. (Output) (See "Notes" below.) 
NOTES 

A directory cannot have its maximum length changed. 

The user must have modify permission on the containing directory. 

The maximum length of a segment is accurate to units of 1024 words, and if 
max_length is not a multiple of 1024 words, it is set to the next multiple of 1024 
words. 

If an attempt is made to set the maximum length of a segment to greater than the 
system maximum, sys_info$max_seg_size, code is set to error_table_$argerr. The 
sys_info data base is described in the Programmer's Reference Manual. 

If an attempt is made to set the maximum length of a segment to less than its 
current length, code is set to error_table_$invalid_max_length. 

The hcs_$set_max_length entry point can be used when a pathname of the segment is 
given, rather than the pointer. 



Name: hcs $set ring brackets 

This entry point, given the directory name and entryname of a nondirectory segment, 
sets the segment's ring brackets. 

USAGE 

declare hcs_$set_r i ng_brackets entry (char (*) , char (*) , 
(3) fixed bin (3), fixed bin (35)); 

call hcs_$set_r i ng_brackets (dir_name, entryname, rb, code); 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment (Input) 

rb 

is a three-element array specifying the ring brackets of the segment; see "Notes" 
below. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

Ring brackets must be ordered as follows: 
rbl <= rb2 <= rb3 

The user must have modify permission on the containing directory. Also, the 
validation level must be less than or equal to both the present value of the first ring 
bracket and the new value of the first ring bracket that the user wishes set. 

Ring brackets and validation levels are discussed in "Intraprocess Access Control" in 
the Programmer's Reference Manual. 



Name: hcs $set safety sw 

This entry point allows the safety switch associated with a segment or directory to be 

changed. The segment is designated by a directory name and an entryname. See 

"Segment, Directory, and Link Attributes" in the Programmer's Reference Manual for a 
description of the safety switch. 

USAGE 

declare hcs_$set_saf ety_sw entry (char (*) , char (*) , bit(l), 
fixed bin (35)) ; 

call hcs_$set_saf ety_sw (dir_name, entryname, safety_sw, code); 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment or directory. (Input) 
safety _sw 

is the new value of the safety switch. (Input) 
"0"b if the segment can be deleted. 
"l"b if the segment cannot be deleted. 

code 

is a storage system status code. (Output) 
NOTES 

The user must have modify permission on the containing directory. 

The hcs_$set_safety_sw_seg entry point can be used when the pointer to the segment 
is given, rather than a pathname. 



Name: hcs $set safety sw seg 

This entry point, given a pointer to a segment, sets the safety switch of the segment. 
See "Segment, Directory, and Link Attributes" in the Programmer's Reference Manual 
for a description of the safety switch. 

USAGE 

declare hcs_$set_saf ety_sw_seg entry (ptr, bit(l), fixed bin (35)): 
call hcs_$set_saf ety_sw_seg (seg_ptr, safety_sw, code); 
ARGUMENTS 
seg_ptr 

is the pointer to the segment. (Input) 
safety_sw 

is the new value of the safety switch. (Input) 
"0"b if the segment can be deleted. 
"l"b if the segment cannot be deleted. 
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code 

is a storage system status code. (Output) 
NOTES 

The user must have modify permission on the containing directory. 

The hcs_$set_safety_sw entry point can be used when a pathname of the segment is 
given, rather than the pointer. 



Name: hcs_$star_ 

This entry point is the star convention handler for the storage system. It is called 
with a directory name and an entryname that is a star name (contains asterisks or 
question marks). The directory is searched for all entries that match the given 
entryname. Information about these entries is returned in a structure. If the 
entryname is **, information on all entries in the directory is returned. 

This entry point returns the storage system type and all names that match the given 
entryname. The hcs_$star_dir_list_ and hcs_$star_list_ entry points described below 
return more information about each entry. The hcs_$star_dir_list_ entry point returns 
only information kept in the directory branch, while the hcs_$star_list_ entry point 
returns information kept in the volume table of contents (VTOC). Accessing the 
VTOC is an additional expense, and it can be quite time consuming to access the 
VTOC entries for all branches in a large directory. Further, if the volume is not 
mounted, it is impossible to access the VTOC. Therefore, use of the hcs_$star_dir_list_ 
entry point is recommended for all applications in which information from the VTOC 
is not essential. 

Status permission is required on the directory to be searched. 
USAGE 

declare hcs_$star_ entry (char (*) , char (*) , fixed bin (2), ptr, 
fixed bin, ptr, ptr, fixed bin(35))» 

call hcs_$star_ (dir_name, star_name, star_select_sw, area_ptr, 
star_entry_count, star_entry_ptr , star_names_ptr , code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
star_name 

is the entryname that can contain asterisks or question marks. (Input) 
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star_select_sw 

indicates what information is to be returned. (Input) It can be: 
star_LINKS_ONLY (=1) 

information is returned about link entries only. 
star_BRANCHES_ONLY (=2) 

information is returned about segment and directory entries only. 
star_ALL_ENTRIES (=3) 

information is returned about segment, directory, and link entries. 

area_ptr 

is a pointer to the area in which information is to be returned. If the pointer is 
null, star_entry_count is set to the total number of selected entries. See "Notes" 
below. (Input) 

star_entry_count 

is a count of the number of entries that match the entryname. (Output) 
star_entry_ptr 

is a pointer to the allocated structure in which information on each entry is 
returned. (Output) 

star_names_ptr 

is a pointer to the allocated array of all the entrynames in this directory that 
match star_name. See "Notes" below. (Output) 

code 

is a storage system status code. See "Status Codes" below. (Output) 
NOTES 

Even if area_ptr is null, star_entry_count is set to the total number of entries in the 
directory that match star_name. The setting of star_select_sw determines whether 
star_entry_count is the total number of link entries, the total number of segment and 
directory entries, or the total number of all entries. 

If area_ptr is not null, the entry information structure and the name array are 
allocated in the user -supplied area. 
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This ds.tE structure is declared in star_structures.incl.pll. The entry information 
structure is as follows: 

del 1 star_entries (star_entry_count) aligned based (star_entry_ptr) , 

2 type fixed bin (2) unsigned unaligned, 

2 nnames fixed bin (16) unsigned unaligned, 

2 n index fixed bin (18) unsigned unaligned; 

STRUCTURE ELEMENTS 

type 

specifies the storage system type of entry (the following named constants are 
declared in star_structures.incl.pll): 

star_LINK (=0) 

star_SEGMENT (=1) 

star_DIRECTORY (=2) 

nnames 

specifies the number of names for this entry that match star_name. 
nindex 

specifies the offset in star_names of the first name returned for this entry. 
NOTES 

All of the names that are returned for any one entry are stored consecutively in an 
array of all the names allocated in the user-supplied area. The first name for any 
one entry begins at the nindex offset in the array. 

The names array, allocated in the user-supplied area and declared in star_structures.incl.pll, 
is as follows: 

del star_names (sum (star_entr i es (*) . nnames)) char (32) 
based (star_names_ptr) ; 

The user must provide an area large enough for the hcs_$star_ entry point to store 
the requested information. 

STATUS CODES 

If no match with star_name was found in the directory, code will be returned as 
error_table_$nomatch. 

If star_name contained illegal syntax with respect to the star convention, code will be 
returned as error_table_$badstar. 



2-473 



AG93-05 



hcs_$star_ 



hcs_$star_dir_list_ 



If the user did not provide enough space in the area to return all requested 
information, code will be returned as error_table_$notalloc. in this case, the total 
number of entries (for hcs_$star_) or the total number of branches and the total 
number of links (for hcs_$star_list_ and hcs_$star_dir_list_) will be returned, to 
provide an estimate of space required. 

USING THE INCLUDE FILE 

A program using star_structures.incl.pll should declare addT, binary, and sum to be 
builtin. The arguments star_entry_count, star_entry_ptr, and star_names_ptr are 
declared in the include file along with named constants for the value of star_select_sw 
and the storage system type. One of the named constants for star_select_sw can be 
passed as an argument to hcs_$star_ along with star_entry_count, star_entry_ptr and 
star_names_ptr. 



Name: hcs $star dir list 

This entry point returns information about the selected entries, such as the mode and 
bit count for branches, and link pathnames for links. It returns only information kept 
in directory branches, and does not access the VTOC entries for branches. This entry 
point is more efficient than the hcs_$star_list_ entry point. 

USAGE 

I declare hcs_$star_d i r_l i st_ entry (char (*) , char (*) , fixed bin (2), ptr, 
| fixed bin, fixed bin, ptr, ptr, fixed bin (35))* 

call hcs_$star_d i r_l i st_ (dir_name, star_name, star_sel ect_sw, area_ptr, 
star_branch_count , star_l i nk_count , star_l i st_branch_ptr , 
star_l i st_names_ptr , code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
star_name 

is the entryname that can contain asterisks or question marks. (Input) 
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star_select_sw 

indicates what information is to be returned. (Input) It can be: 
star_LINKS_ONLY (=1) 

information is returned about link entries only. 
star_BRANCHES_ONLY (=2) 

information is returned about segment and directory entries only. 
star_ALL_ENTRIES (=3) 

information is returned about segment, directory, and link entries. 
star_LINKS_ONLY_WITH_LINK_PATHS (=5) 

information is returned about link entries only, including the pathname 

associated with each link entry. 
. star_ALL_ENTRIES_WITH_LINK_PATHS (=7) 

information is returned about segment, directory, and link entries, including 

the pathname associated with each link entry. 

area_ptr 

is a pointer to the area in which information is to be returned. If the pointer is 
null, star_branch_count and star_link_count are set to the total number of selected 
entries. See "Notes" below. (Input) 

star_branch_count 

is a count of the number of segments and directories that match the entryname. 
(Output) 

star_link_count 

is a count of the number of links that match the entryname. (Output) 
star_list_branch_ptr 

is a pointer to the allocated structure in which information on each entry is 
returned. (Output) 

star_list_names_ptr 

is a pointer to the allocated array in which selected entrynames and pathnames 
associated with link entries are stored. (Output) 

code 

is a storage system status code. See "Status Codes" above in the description of 
hcs_$star_ entry point. (Output) 

NOTES 

The names star_LINKS_ONLY through STAR_ALL_ENTRIES_WITH_LINK_PATHS are 
declared in star_structures.incl.pll. The star_LINKS_ONLY, star_BRANCHES_ONLY, 
and star_ALL_ENTRIES are declared fixed bin (2) for compatability with hcs_$star 
and the star_LINKS_ONLY_WITH_LINK_PATHS and 

star_ALL_ENTRIES_WITH_LINK_PATHS are declared as fixed bin (3). 
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Even if area_ptr is null, star_branch_count and star_link_count may be set. If 
information on segments and directories is requested, star_branch_count is set to the 
total number of segments and directories that match star_name. If information on 
links is requested, star_link_count is the total number of links that match star_name. 

If area_ptr is not null, an array of entry information structures and the names array, 
as described in the hcs_$star_ entry point above, are allocated in the user-supplied 
area. Each element in the structure array may be either of the structures described 
below (the star_links structure for links or the star_list_branch structure for segments 
and directories). The correct structure is indicated by the type item, the first item in 
both structures. 

If the system is unable to access the VTOC entry for a branch, values of zero are 
returned for records used, date_time_contents_modified, and date_time_used, and no 
error code is returned. Callers of this entry point should interpret zeros for all three 
of these values as an error indication, rather than as valid data. 

The first three items in each structure are identical to the ones in the structure 
returned by the hcs_$star_ entry point. 

The following structure, declared in star_structures.incl.pll, is used if the entry is a 
link: 

del 1 star_links (star_branch_count + star_l i nk_count) 

aligned based (star_l i st_branch_ptr) , 
2 type fixed binary (2) unsigned unaligned, 

2 nnames fixed binary(l6) unsigned unaligned, 

2 n index fixed binary (1 8) unsigned unaligned, 

2 dtem bit (36) unaligned, 

2 dtd bit (36) unaligned, 

2 pathname_l en fixed binary (18) unsigned unaligned, 
2 pathname_i ndex fixed binary 08) unsigned unaligned; 

STRUCTURE ELEMENTS 

type 

specifies the storage system type of entry: 
star_LINK (=0) 
star_SEGMENT (=1) 
star_DIRECTORY (=2) 

nnames 

specifies the number of names for this entry that match star_name. 
nindex 

specifies the offset in star_list_names of the first name returned for this entry, 
dtem 

is the date and time the link was last modified. 
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did 

is the date and time the link was last dumped. 
pathname_len 

is the number of significant characters in the pathname associated with the link. 

pathname_index 

is the index in star_list_names of the link pathname. 

If the pathname associated with each link was requested, the pathname is placed in 
the names array and occupies as many units as are needed. The index of the first 
unit is specified by pathname_index in the links array. The length of the pathname is 
given by pathnamejen in the links array. 

The following structure is the array of names. It is declared in star_structures.incl.pll. 

del star_l i st_names char (32) based (star_l i st_names_ptr) 

dimension (star_links (star_branch_count + star_l i nk_count) . ni ndex 
+ star_links (star_branch_count + star_l i nk_count) .nnames 
+ divide (star_links (star_branch_count + star_l i nk_count) . pathname_l en 
+ 31. 32, 17, 0) 
"binary ( 

(star_links (star_branch_count + star_l ink_count) .type = star_LINK) 
& (star_select_sw >= star_L I NKS_ONLY_WITH_L I NK_PATHS) , 1)); 

The following based variable is used to get the pathname associated with link 
star_linkx in the starjinks array. It is declared in star_structures.incl.pll. 

del star_l i nk_pathname char (star_links (star_l i nkx) . pathname_l en) based 
(addr (star_l i st_names (star_links (star_l i nkx) . pathname_i ndex) ) ) ; 

Use the following structure if the entry is a segment or a directory. The 
star_dir_list_branch structure is the same as the star_list_branch structure except for 
the dtem and bit-count fields. This structure is declared in star_structures.incl.pll. 

del 1 star_d i r_l i st_branch (star_branch_count + star_l i nk_count) 



aligned based (star_l i st_branch_ptr) , 



2 


type 


f 


xed binary (2) unsigned unaligned, 


2 


nnames 


f 


xed binary (16) unsigned unaligned, 


2 


ni ndex 


f 


xed binary (18) unsigned unaligned, 


2 


dtem 


b 


t (36) unal i gned, 


2 


pad 


b 


t (36) unal i gned, 


2 


mode 


b 


t (5) unal igned, 


2 


raw_mode 


b 


t (5) unal igned, 


2 


master_d i r 


b 


t (1) unal igned, 


2 


b i t_count 


f 


xed binary (2b) unaligned; 



2-477 



AG93-05 



hcs_$star_diT_list_ 



hcs_$star_dir_list_ 



STRUCTURE ELEMENTS 
type 

specifies the storage system type of entry: 
star_LINK (=0) 
star_SEGMENT (=1) 
star.DIRECTORY (=2) 



nnames 

specifies the number of names for this entry that match star_name. 
nindex 

specifies the offset in star_list_names of the first name returned for this entry, 
dtem 

is the date and time the directory entry for the segment or directory was last 
modified. 

pad 

is unused space in this structure 
mode 

is the current user's access mode to the segment or directory. See the "Notes" 
section in the description of hcs_$get_user_effmode in this manual for a more 
detailed description of access modes. 

raw_mode 

is the current user's access mode before ring brackets and access isolation are 
considered. 

master_dir 

specifies whether entry is a master directory: 
*T'b yes 
"0"b no 

bit_count 

is the bit count of the segment or directory. 
NOTES 

The star_links structure described for hcs_$star_list is used if the entry is a link. 
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Name: hcs__$star__list__ 

This entry point returns more information about the selected entries, such as the mode 
and records used for segments and directories and link pathnames for links. This 
entry point obtains the records used and the date of last modification and last use 
from the VTOC, and is, therefore, more expensive to use than the hcs_$star_dir_list_ 
entry point. 

USAGE 

declare hcs_$star_l i st_ entry (char (*) , char (*) , fixed bin(3), ptr, 
fixed bin, fixed bin, ptr, ptr, fixed bin (35)); 

call hcs_$star_l i st_ (dir_name, star_name, star_sel ect_sw, area_ptr, 

star_branch_count , star_l i nk_count , s tar_l i st_branch ptr, 

star_l i st_names_ptr , code); 

ARGUMENTS 



The arguments are exactly the same as those for the hcs_$star_dir_list_ entry point 
above. 



NOTES 



The notes for hcs_$star_dir_list_ also apply to this entry. 

The following structure, declared in star_structures.incl.pll, is used if the entry is a 

CPOTYion t nr o Hiro>»tATTf 

del 1 star_i i st_branch (star_branch_count + star_l i nk_count) 

aligned based (star_l i st_branch_ptr) , 



2 


type 


f 


xed binary (2) unsigned unaligned, 


2 


nnames 


f 


xed binary (16) unsigned unaligned, 


2 


n i ndex 


f 


xed binary (18) unsigned unaligned, 


2 


dtcm 


b 


t (36) unal i gned, 


2 


dtu 


b 


t (36) unal i gned, 


2 


mode 


b 


t (5) unal i gned, 


2 


raw_mode 


b 


t (5) unal igned, 


2 


master_d i r 


b 


t (1) unal igned, 


2 


pad 


b 


t (7) unal igned, 


2 


records 


f 


xed bin (1 8) unsigned unaligned; 



STRUCTURE ELEMENTS 



type 

specifies the storage system tvpe of entry: 
star_LINK (=0) 
star_SEGMENT (=1) 
star.DIRECTORY (=2) 
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nnames 

specifies the number of names for this entry that match star_name. 
nindex 

specifies the offset in star_list_names of the first name returned for this entry, 
dtcm 

is the date and time the contents of the segment or directory were last modified. 

dtu 

is the date and time the segment or directory was last used, 
mode 

is the current user's access mode to the segment or directory. 
raw_mode 

is the current user's access mode before ring brackets and access isolation are 
considered. 

master_dir 

specifies whether entry is a master directory: 
"l"b yes 
"0"b no 

pad 

is unused space in the structure, 
records 

is the number of 1024-word records of secondary storage that have been assigned 
to the segment or directory. 



Name: hcs__$status__ 

This entry point returns the most often needed information about a specified directory 
entry. Other entry points (hcs_$status_long, hcs_$status_minf, hcs_$status_mins) return 
more or less detailed information, and should be selected as the user requires. 

USAGE 

declare hcs_$status_ entry (char (*) , char (*) , fixed bin(l), ptr, ptr, 
fixed bin (35) ) 5 

call hcs_$status_ (dir_name, entryname, chase_sw, status_ptr, 
status_area_ptr , code); 
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ARGUMENTS 



dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment, directory, or link. (Input) 
chase_sw 

indicates whether the information returned is about a link or about the entry to 
which the link points. (Input) 

0 returns link information. 

1 returns information about the entry to which the link points. 
status_ptr 

is a pointer to the structure in which information is returned. (Input) See "Entry 
Information" below. 

status_area_ptr 

is a pointer to the area in which names are returned. (Input) If the pointer is 
null, no names are returned (see "Notes" below). 

code 

is a storage system status code. (Output) One of the possible codes returned can 
be: 

error_table_$no_s_permission 

The user lacks status permission on the containing directory, but has non-null 
access to the object. When this code is returned, all values in the status 
structure are valid, except for the offset of the array of names — no 
information on names is available if this error code is returned. 



ENTRY INFORMATION 



The status_ptr argument points to the following structure (defined in the include file 
status_structures.incl.pll) if the entry is a segment or directory: 



del 1 status_branch 
2 short 
3 type 
3 nnames 
3 names_relp 
3 dtcm 
3 dtu 
3 mode 
3 raw_mode 
3 padl 

3 records used 



aligned based (status_ptr) , 
al i gned, 

fixed bin (2) unaligned unsigned, 
fixed bin (16) unaligned unsigned, 



(18) unal i gned, 
(36) unal i gned, 
(36) unal i gned, 
(5) unal i gned, 
(5) unal i gned, 
(8) unal i gned, 



bit 
bit 
bit 
bit 
bit 
bit 

fixed bin (18) unaligned unsigned; 
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STRUCTURE ELEMENTS 
type 

specifies the type of entry: 

0 link 

1 segment 

2 directory 

the named constants Link, Segment and Directory are declared in 
status_structures. incl. pi 1. 

nnames 

specifies the number of names for this entry. It is set to zero if no names are 
allocated. 

names_relp 

is a pointer (relative to the base of the segment containing the user-specified free 
storage area) to an array of names. It is set to zero if no names are allocated. 

dtcm 

contains the date and time the contents of the segment or directory were last 
modified. 

dtu 

contains the date and time the segment or directory was last used, 
mode 

contains the effective mode of the segment with respect to the current user's 
validation level. See the hcs_$append_branchx entry point for a description of 
modes. The values of these bits are the same as for the fixed bin (5) mode 
argument of the hcs_$append_branchx entry point 

raw_mode 

is the mode of the segment with respect to the current user without regard to 
ring brackets, etc. See the hcs_$append_branchx entry point for a description of 
modes. 

padl 

is unused space in this structure. 
records_used 

contains the number of 1024- word records of secondary storage assigned to the 
segment or directory. 
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The status_ptr argument points to the following structure, (defined in the include file 
status_structures.incl.pll) if the entry is a link: 



del 1 status_l i nk 
2 type 
2 nnames 
2 names_relp 
2 dtem 
2 dtd 

2 pathname_l ength 
2 pathname_rel p 



aligned based (status_ptr) , 
fixed bin (2) unaligned unsigned, 
fixed bin (16) unaligned unsigned, 
bit (18) unal igned, 
bi t (36) unal i gned, 
b i t (36) una 1 i gned , 
fixed bin (17) unaligned, 
bit (18) unal igned; 



STRUCTURE ELEMENTS 
type 

specifies the type of entry: 

0 link 

1 segment 

2 directory 

the named constants Link, Segment and Directory are declared in 
status_structures.incl.pll. 

nnames 

specifies the number of names for this entry. It is set to zero if no names are 
allocated. 

names_relp 

is a pointer (relative to the base of the segment containing the user -specified 
storage area) to an array of names. It is set to zero if no names are allocated. 

dtem 

contains the date and time the link was last modified. 

dtd 

contains the date and time the link was last dumped by the hierarchy dumper. 
pathname_length 

specifies the length in characters of the link pathname. It is set to zero if the 
pathname is not allocated. 

pathname_relp 

is a pointer (relative to the base of the segment containing the user-specified free 
storage area) to the link pathname. It is set to zero if the pathname is not 
allocated. 

NOTES 

The user must provide the storage space required by the above structures. The 
hcs_$status_ entry point merely fills them in. 
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If the status_area_ptr argument is not null, entrynames are returned in the following 
structure (defined in include file status_structures.incl.pll) allocated in the user-specified 
area: 

del status_entry_names (status_branch .nnames) character (32) aligned 
based (pointer (status_area_ptr , status_branch . names_rel p) ) ; 

The first name in this array is defined as the primary name of the entry. The user 
must provide an area that is large enough to accommodate a reasonable number of 
names. If for any reason the entrynames cannot be allocated, status_branch.names_relp 
will be zero. 

Link pathnames are returned using the following declaration (defined in include file 
status_structure.incl.pll) allocated in the user-specified area: 

del status_pathname character (status_l i nk . pathname_l ength) aligned 
based (pointer (status_area_ptr , status_l i nk .pathname_rel p) ) ; 

If for any reason the link pathname cannot be allocated. status_link.pathname_relp will 
be zero. 

For compatibility with older programs, if entryname is given as a null string, status is 
returned on the directory dir_name. 

ACCESS REQUIREMENTS 

The user must have either status permission on the containing directory or nonnull 
access to the object to obtain complete information. Entrynames, however, are not 
returned unless the user has status permission on the containing directory. 



Name: hes Sstatus long 

This entry point returns most user-accessible information about a specified entry. 
USAGE 

declare hcs_$status_l ong entry (char (*) , char (*) , fixed bin(l), ptr, 
p*tr , f i xed bin (35) ) 5 

call hcs_$status_long (dir_name, entryname, chase_sw, status_ptr, 
status_area_ptr , code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
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entryname 

is the entryname of the segment, directory, or link. (Input) 
chase_sw 

indicates whether the information returned is about a link or about the entry to 
which the link points. (Input) 

0 returns link information 

1 returns information about the entry to which the link points 
status_ptr 

is a pointer to the structure in which information is returned. (Input) See "Entry 
Information" below. 

status_area_ptr 

is a pointer to the area in which names are returned. (Input) If the pointer is 
null, no names are returned (see "Entry Information" below). 

code 

is a storage system status code (see "Access Requirements" below). (Output) One 

of the possible codes returned can be: 

error_table_$no_s_permission 

The user lacks status permission on the containing directory, but has non-null 
access to the object When this code is returned, all values in the status 
structure are valid, except for the offset of the array of names — no 
information on names is available if this error code is returned. 

ACCESS REQUIREMENTS 

The user must have either status permission on the containing directory or nonnull 
access to the object to obtain complete information. Entrynames, however, are not 
returned unless the user has status permission on the containing directory. 

NOTES 

For compatability with older programs, if entryname is given as a null string, status is 
returned on the directory dir_name. 

ENTRY INFORMATION 

The entry_ptr argument points to the same structure as described under the 
hcs_$status_ entry point if the entry is a link. If the entry is a segment, directory, 
or multisegment file, it points to the following structure (defined in include file 
status_struc tur es. incl. pi 1 ) : 
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atus_branch 


aligned based (status_ptr) , 


short 


a 1 i gned , 


3 type 


fixed bin (2) unaligned unsigned, 


3 nnames 


fixed bin (16) unaligned unsigned, 


3 names relp 


bit (l8) unaligned, 


3 dtcm 


bit (3&) unaligned, 


3 dtu 


bit (36) unaligned, 


3 mode 


bit (5) unaligned, 


3 raw mode 


bit (5) unaligned, 


3 padl 


bit (8) unaligned, 




f I y *»ri h i n flRl una 1 i nnpri un^ i nnpri 
i i a cu u i ii y i w/ una i i y 1 1 uiiw i vjiicuj 


1 ona 


a 1 i fined 


3 dtd 


bit (3^) unaligned, 


3 d tern 


bit (36) unal igned, 


3 lvid 


bi t f^6) unal ianed. 


3 current length 


fixed bin (12) unaligned unsigned, 


3 b i t count 


fixed bin (2*0 unaligned unsigned, 


3 pad2 


bit (8) unal i gned, 


3 copy_swi tch 


bit (1) unal i gned. 


3 tpd sw itch 


bit ( 1 ) una 1 i gned . 


3 md i r_swi tch 


bit (1) unal i gned, 


3 damaged swi tch 


bit (1) unal i gned, 


3 pad3 


bit (6) unal i gned, 


3 ring brackets 


(0:2) fixed bin (6) unaligned unsigned, 


3 uid 


bi t (36) unal igned; 



STRUCTURE ELEMENTS 



type 

specifies the type of entry: 

0 link 

1 segment 

2 directory 

the named constants Link, Segment and Directory are declared in 
status_structures.incl.pll. 

nnames 

specifies the number of names for this entry. It is set to zero if no names are 
allocated. 

names_relp 

is a pointer (relative to the base of the segment containing the user-specified free 
storage area) to an array of names. It is set to zero if no names are allocated. 

dtcm 

contains the date and time the contents of the segment or directory were last 

modified. 

dtu 

contains the date and time the segment or directory was last used. 
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mode 

contains the effective mode of the segment with respect to the current user's 
validation level. For directory entries, the 4-bit is 1 (00100b). 

raw_mode 

is the mode of the segment with respect to the current user without regard to 
ring brackets, etc. See the hcs_$append__branchx entry point for a description of 
modes. 

padl 

is unused space in this structure. 
records_used 

contains the number of 1024-word records of secondary storage assigned to the 
segment or directory. 

dtd 

is the date and time the segment was last dumped by the hierarchy dumper, 
dtem 

is the date and time the entry was last modified. 

lvid 

is the ID of the logical volume on which this entry resides. 
current_length 

is the current length of the segment in units of 1024-word records. 
bit_count 

is the bit count associated with the segment if type is 1. If type is 2, then this 
is zero for a directory, otherwise it is the number of components for a 
multisegment file. 

pad2 

is unused space in this structure, 
copy _swi ten 

contains the setting of the segment copy switch. 

"0"b the default action on initiate in not to produce a copy. 

"l"b the default action on initiate is to produce a copy. 

tpd_switch 

is obsolete and always returned as "0"b. 

mdir_switch 

is the master directory switch. It can be: 
"0"b directory is not a master directory. 
'T'b directory is a master directory. 
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damaged_switch 

contains the setting of the damaged switch for the segment. 

"0"b segment is undamaged or damage is undetected or user has previously reset 
the switch. 

"l"b system has detected damage to the contents of the segment. 

pad3 

is unused space in this structure. 

ring_brackets 

contains the ring brackets of the segment. 

uid 

is the segment unique identifier. 
NOTES 

See the hcs_$status_ entry point for a description of the status_entry_names array. 



Name: hcs Sstatus minf 

This entry point returns the bit count and entry type given the name of a directory 
and an entry. Status permission on the directory or nonnull access on the entry is 
required to use this entry point. 

USAGE 

declare hcs_$status_mi nf entry (char (») , char (*) , fixed bin(l), 
fixed bin (2), fixed bin (24), fixed bin (35)); 

call hcs_$status_m i nf (dir_name, entryname, chase_sw, type, bit_count, 
code) ; 

ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment, directory, or link. (Input) 
chase_sw 

indicates whether the information returned is about a link or about the entry to 
which the link points. (Input) 

U ICtUilia 1111 ft. 1111 \Jl mauim. 

1 returns information about the entry to which the link points. 
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type 

specifies the type of entry. (Output) It can be: 

0 link 

1 segment 

2 directory 

bit_count 

is the bit count. (Output) 

code 

is a storage system status code. (Output) 



Name: hcs Sstatus mins 

This entry point returns the bit count and entry type given a pointer to the segment. 
Status permission on the directory or nonnull access to the segment is required to use 
this entry point. 

USAGE 

declare hcs_$status_mi ns entry (ptr, fixed bin (2), fixed bin (2 k), 
fixed bin (35) ) ; 

call hcs_$status_mi ns (seg_ptr, type, bit_count, code); 

ARGUMENTS 

seg_ptr 

points to the segment about which information is desired. (Input) 

type 

specifies the type of entry. (Output) It can be: 

0 link 

1 segment 

2 directory 

bit_count 

is the bit count. (Output) 

code 

is a storage system status code. (Output) 
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Name: hcs Struncate file 

This entry point, given a pathname, truncates a segment to a specified length. If the 
segment is already shorter than the specified length, no truncation is done. The effect 
of truncating a segment is to store zeros in the words beyond the specified length. 

USAGE 

declare hcs_$ truncate_f i 1 e entry (char (*) , char (*) , fixed bin (19), 
fixed bin (35) ) ; 

call hcs_$truncate_f i 1 e (dir_name, entryname, length, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segmenL (Input) 
length 

is the new length of the segment in words. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have write access on the segment in order to truncate it. 
A directory cannot be truncated. 

A segment is truncated as follows: all full pages after the page containing the last 
word of the new length segment (as defined by the length argument) are discarded. 
The remainder of the page containing the last word is converted to zeros. 

Bit count is not automatically set by the hcs_$truncate_file entry point. If desired, bit 
count may be set by using the hcs_$set_bc entry point. 

The hcs_$truncate_seg entry point performs the same function when given a pointer to' 
the segment instead of the pathname. 
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Name: hcs Svalidate processid 

This entry determines whether a 36-bit quantity is the unique identifier of a process 
which is currently active on the system. 

USAGE 

declare hcs_$val idate__processid entry (bit (36) aligned, fixed bin (35)); 

call hcs_$val i date_process i d (processid, code); 

ARGUMENTS 

processid 

contains a quantity which may be the unique identifier of an active process. 
(Input) 

code 

is a standard status code. (Output) If processid is the unique identifier of an 
active process, the value returned is zero. Otherwise, the value is 
error_table_$process_unknown. 



Name: hcs Swakeup 

This entry point sends an interprocess communication wakeup signal to a specified 
process over a specified event channel. If that process has previously called the 
ipc_$block entry point, it is awakened. See the ipc_ subroutine description. 

USAGE 

declare hcs_$wakeup entry (bit (36) aligned, fixed bin (71), 
fixed bin(7D, fixed bin(35)); 

call hcs_$wakeup (process_id, channel_id, message, code); 

ARGUMENTS 

processed 

is the process identifier of the target process. (Input) 
channeled 

is the identifier of the event channel over which the wakeup is to be sent 
(Input) 

message 

is the event message to be interpreted by the target process. (Input) 
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code 

is a standard status code. (Output) 



Name: heap manager 



Entry: heap__manager__$push heap level 

This entry point creates a new heap level, allocates the heap header and chains the 
previous heap to the current heap. If the stack_header_ptr is null an error of 
error_table_$null_info_ptr is returned. 

USAGE 

declare heap_manager_$push_heap_l evel entry (pointer, 
fixed bi n (1 7) , fixed bin (35)); 

call heap_manager_$push_heap__i evel (stack_header_ptr , exe_ievei, code); 

ARGUMENTS 

stack_header_ptr 

is a pointer to the stack header. This can be obtained via the PL/1 builtin 
stackbaseptrO. (Input) 

exe_level 

is the new execution level after the new heap is created. (Output) 

code 

is a standard status code. (Output) 



Entry: heap manager Spop heap level 

This entry point resets the heap to the previous level freeing the old heap and any 
variables allocated therein. 

USAGE 

declare heap manager_$pop__heap level entry (pointer, 
fixed bin (35)) J 

call heap_manager_$pop_heap_1 evel (stack_header_ptr , code); 



11/86 



2=492 



AG93-05A 



heap_manager_ 



heap_manager_ 



ARGUMENTS 
stack_header_ptr 

is a pointer to the stack header. This can be obtained via the PL/1 builtin 
stackbaseptrO. (Input) 

code 

is a standard status code. (Output) 



Entry: heap manager $get heap header 

This entry point returns a pointer to the heap header for the specified execution level. 

If the execution level does not exist an error of error_table_$no_heap_defined is 
returned. 

USAGE 

declare heap_manager_$get_heap_header entry (pointer, 
fixed b i n (1 7) » pointer, fixed bin(35))» 

call heap__manager_$get_heap_header (stack_header__ptr , exe_level, 
heap_header_ptr , code); 

ARGUMENTS 

exejevel 

is the execution level of the heap required. If a -1 is passed then the current 

execution level is used. (Input) 

stack_header_ptr 

is a pointer to the stack header. This can be obtained via the PL/1 builtin 
stackbaseptrO. (Input) 

heap_header_ptr 

is a pointer to the heap header for the passed execution level. (Output). 

code 

is a standard status code. (Output) 
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Entry: heap manager $get heap level 

This entry point returns the current execution level from the current heap header. If 
the heap does not exist an execution level of -1 is returned. 

USAGE 

declare heap_manager_$get__heap_l evel entry (pointer) 
returns (fixed bin (17)); 

exe_level = heap_manager_$get_heap_l evel (stack_header_ptr) ; 

ARGUMENTS 

stack_header_ptr 

is a pointer to the stack header. This can be obtained via the PL/1 builtin 
stackbaseptrO. (Input) 



Entry: heap manager $get heap area 

This entry point returns a pointer to the heap area for the specified level. The area 
is max_segsize - 50 words. If the heap level specified does not exist an error of 
error_table_$no_heap_defined is returned. 

USAGE 

declare heap__manager_$get_heap_area entry (pointer, fixed b i n ( 1 7) » 
pointer, fixed bin (35)); 

call heap_manager_$get_heap_area (stack_header_ptr , exe_l eve 1 , 
heap_area_ptr , code); 

ARGUMENTS 

exejevel 

is the execution level of the heap area required. If a -1 is passed then the 
current execution level is used. (Input) 

stack_header_ptr 

is a pointer to the stack header. This can be obtained via the PL/1 builtin 
stackbaseptrO. (Input) 

heap_area_ptr 

is pointer to the heap area for the passed level. (Output) 

code 

is a standard status code. (Output) 
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Name: help_ 

The help_ subroutine performs the basic work of the help command The help_ 
subroutine is called to print selected information from one or more info segments. 
The caller may select: what information is to be printed; what search list is to be 
used to find the info segments; what suffix the info segments must have. Thus, the 
help_ provides an interface for implementing a subsystem help command. 

Several entry points in • the help_ subroutine are described below. help_$init must be 
called before calling the help_ or help_$check_info_segs entry points. The help_ or 
help_$check_info_segs entry points may then be called one or more times. When the 
caller no longer needs the help_args structure, help_$term must be called to release 
the temporary segment containing the help_args structure. 

The help_ entry point searches for info segments, selects information blocks (infos), 
and prints the information. The caller provides information in the help_args structure 
(obtained in the call to help_$init) to select the infos to be printed and the type of 
information to be printed. 

The help_ subroutine may ask the user questions about how much information should 
be printed. These questions and the responses the user may give are in the description 
of the help command. Questions are asked using the command_query_ subroutine. 

USAGE 

declare help_ entry (char (*) , ptr, char (*) , fixed bin, fixed bin (35)); 
call help_ (caller, Phelp_args, suffix, progress, code); 
ARGUMENTS 
caller 

is the name of the calling program, on whose behalf the temporary segment 
containing the help_args structure is obtained. (Input) 

Phelp_args 

is a pointer to the help_args structure, described under "Information Structure" 
below. (Output) 

suffix 

is the suffix which must appear in the entrynames of info segments to be 
processed by this invocation of help_. This suffix is also assumed when omitted 
from the (final or only) entryname of values given for help_args.path. value in the 
help_args structure (see "Information Structure" below). If a null string is given, 
then no suffix is required in info segment entrynames, and none is assumed in 
values of help_args.path. value. (Input) 
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progress 

is a special status code that indicates which stage of processing help_ was 
performing when an error occurs. (Output) The following values may be returned: 

1 the Phelp_args argument points to an unimplemented version of the help_args 
structure. 

2 help_args.Npaths is not positive, indicating that no info_names were given. 
help_ is unable to select info segments for printing. 

3 an error is encountered while evaluating one or more of the help_args. path. value 
values, help_args.path.code indicates the particular error encountered in each 
value. 

4 no fatal errors are encountered. Some infos matching help_args.path were 
found. Any nonfatal errors encountered while finding the infos are diagnosed 
to the user, unless help_args_.Sctl.inhibit_errors is on. A list of infos to be 
compared with the -section and -search criteria is created. 

5 infos matching the -section and -search criteria are printed. A nonzero code 
argument is returned only when no infos match the -section and -search 
criteria. help_ does not report such an error to the user. The caller is 
responsible for doing this. 

code 

is a standard status code. (Output) When progress is 1, the code may have the 
following value: 

error_table_$unimplemented_version 

help_ does not support the version of the help_args structure pointed to by 
the Phelp_args pointer argument. 

When progress is 2, the code may have the following value: 
error_table_$noarg 

help_args.Npaths was not positive. 

When progress is 3, the code may have any value returned by 

expand_pathname_$add_suffix or check_star_name_$entry, or it may have the 

following value: 

error_table_$inconsistent 

a star name was given when help_args.Sctl.ep = "l"b, or when a value of 
help_args. path. value contains a subroutine entry point name. 

When progress is 4, the code may have the following value: 

error_table_$nomatch 

no info segments match any of the help_args.path elements. For each 
help_args.path.value element, help_ prints an error message when no matching 
info segments are found. 

When progress is 5, the code may have the following value: 

error_table_$nomatch 

none of the infos selected by help_args.path contain sections whose titles 
match the selection criteria given in help_args.scn, or paragraphs that match 
the selection criteria given in help_args.srh. help_ does not report this error 
to the user. The caller of help_ must do this. 
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INFORMATION STRUCTURE 

The Phelp_args argument points to the following structure, which is declared in 
help_args_.incl.pll: 



2 Sctl, 
(3 he_only, 
3 he_pn 

3 he_i nf o_name, 

3 he_counts, 

3 title, 

3 sen, 

3 srh, 

3 bf, 

3 ca, 

3 ep, 

3 all, 

3 inhibi t__errors) bit ( 1 ) unal, 

3 mbzl bit (24) unal , 



2 


Nsearch_di rs 




fixed bin, 


2 


Npaths 




fixed bin, 


2 


Ncas 




fixed bin, 


2 


Nscns 




fixed bin, 


2 


Nsrhs 




fixed bin, 


2 


mi n_Lpgh 




fixed bin, 


2 


max_Lpgh 




fixed bin, 


2 


Ls n 3cs between 


i nf os 


f i xed bin, 


2 


mi n__date_t ime 




f ixed bin (71) » 


2 


sci ptr 




ptr, 


2 


pad2 (8) 




fixed bin, 


2 


search_dirs (0 


refer 


(help args.Nsearch dirs)) char(l68) unal, 


2 


path (0 refer 


(hel p_args .Npaths) ) , 




3 value 




char (425) vary i ng, 




3 info name 




char (32) unal, 




3 dir (1) 




char (168) unal , 




3 ent 




char (32) unal, 




3 ep 




char (32) varying, 




3 code 




fixed bin (35) , 




3 S, 







(h pn_ctl__arg, 
k i nf o_name = not = s tar name, 
k 1 ess_greater , 
k starname_ent, 
h starname_i nf o_name, 

k separate_i nfo_name) bit(l) unal, 

k pad3 bit (30) unal , 



del 1 help_args 
2 version 



aligned based (Phelp_args) , 
fixed bin, 
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2 ca (0 refer (hel p_args .Ncas) ) char (32) varying, 
2 sen (0 refer (hel p_args .Nscns) ) char (80) varying, 
2 srh (0 refer (hel p_args .Nsrhs) ) char (80) varying, 
Phelp_args ptr, 
Vhelp_args_2 fixed bin int static 

opt ions (constant) init(2); 

STRUCTURE ELEMENTS 
version 

is the version number of this structure (currently 2). The variable Vhelp_args_2 
should be used when checking this version number. 

Sctl 

are flags controlling the operations which help_ performs on the info segments. 
help_$init sets all of these flags to "0"b. 

Sctl.he_only 

help_ prints only a heading line identifying matching info segments. The heading 
line includes the info heading, plus heading fields selected by Sctl.he_pn, 
Sctl. he_inf o_name and Sctl.he_counts. No other information is printed. This flag 
is mutually exclusive with ail other Sctl flags except those named above, Scti.scn 
and SctLsrh. 

Sctl.he_pn 

help_ includes the info pathname in all heading lines. help_ prints other 
information along with the heading line, as requested by the other Sctl flap. If 
no other flags are set, help_ prints the heading line followed by the first 
paragraph of information. 

Sctl. he_inf o_name 

help_ includes the info_name in all heading lines. This info_name is included 
only when help_args.path identifies an info segment containing more than one 
information block (info). help_ prints other information along with the heading 
line, as requested by other Sctl flags. If no other flags are set, help_ prints the 
heading line followed by the first paragraph of information. 

Sctl.he_counts 

help_ includes info line counts and subroutine info entry point counts in all 
heading lines. help_ prints other information along with the heading line, as 
requested by other Sctl flags. If no other flags are set, help_ prints the heading 
line followed by the first paragraph of information. 

Sctl. title 

help_ prints all section titles (including section line counts), then asks if the user 
wants to see the first paragraph. Normally, help_ just begins printing the first 
paragraph. 
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Sctl.scn 

help_ searches section titles for one containing all of the substrings given in 
help_args.scn. If a matching title is found, help_ begins printing information 
requested by other Sctl flags. If no other flags are set, help_ prints the first 
paragraph of the matching section. If no matching title is found, help_ skips the 
info without comment 

SctLsrh 

help_ searches all paragraphs for one containing all of the substrings given in 
help_args.srh. If a matching paragraph is found, help., begins printing information 
requested by other Sctl flags. If no other flags are set, help_ prints the matching 
paragraph. If no matching paragraph is found, help_ skips the info without 
comment. If SctLscn is also "l"b, then only paragraphs from the matching section 
to the end of the info are searched. 

Sctl.bf 

help_ prints only a brief summary of an info describing a command, active 
function, or subroutine. This flag is mutually exclusive with all other Sctl flags 
except Sctl.he_pn, Sctl.he_info_name, Sctl.he_counts, Sctlxa, Sctl.scn and SctLsrh. 

Sctlxa 

for an info describing a command, active function, or subroutine, help_ prints 
only the descriptions of one or more arguments or control arguments identified by 
the substrings in help_args.ca. This flag is mutually exclusive with all other Sctl 
flags except Sctl.he_pn, Sctl.he_info_name, Sctl.he_counts, Sctl.bf, SctLscn and 
SctLsrh. 

SctLep 

help_ prints information describing the main entry point of a subroutine, rather 
than information describing the general characteristics of all subroutine entry 
points. 

SctLall 

help_ prints all of the info without asking the user any questions. 
Sctl.inhibit_errors 

help_ suppresses error messages which it normally prints to diagnose failure to 
find a given info or entry point within a subroutine info. If no matching infos 
are found, then help_ still returns a code of error_table_$nomatch. 

SctLmbzl 

is reserved for future use. help_$init sets this field to ""b. 
Nsearch_dirs 

is the number of directories help_ searches for info segments. The directory 
pathnames are given in help_args.search_dirs. This number is set by help_$init to 
the number of paths in the search list named in the call to help_$init, but the 
caller may change it before calling help_. 
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Npaths 

is the number of info names help_ searches for. The names are given in 

help_args.path. The caller must set this number before calling help_. help_$init 
initializes it to zero. 



Ncas 

is the number of substrings help_ uses in searching for argument or control 
argument descriptions when help_args.Sctl.ca is given. The substrings are given in 
help_args.ca. help_$init initializes this number to zero. 

Nscns 

is the number of substrings help_ uses in searching for a matching section title 

when help_args.Sctl.scn is given. The substrings are given in help_args.scn. 
help_$init initializes this number to zero. 

Nsrhs 

is the number of substrings help_ uses in searching for a matching paragraph 

when help_args.Sctl.srh is given. The substrings are given in help_args.srh. 
help_$init initializes this number to zero. 

min_Lpgh 

is the length (in lines) of the shortest paragraph that help_ will consider as a 
distinct unit. Paragraphs shorter than this may be printed with their preceding 
paragraph, rather than asking the user if he wants to see the short paragraph. 
help_$init initializes this number to 4. 

max_Lpgh 

is the maximum number of lines of information that help_ allows in grouped 
paragraphs before asking the user whether he wants to see more. help_ will never 
group short paragraphs with their preceding paragraph if the total number of lines 
to be printed (including 2 blank lines between paragraphs) would exceed this 
number. help_$init initializes this number to 15. 

Lspace_between_inf os 

is the number of blank lines which help_ prints between the last paragraph of 

one info and the heading line (or first paragraph) of the next. help_$init 
initializes this number to 2. 



min_date_time 

is a Multics clock value. Only infos modified on or after the time given in this 
clock value are selected. Info modification time is based upon the 
date_time_entry_modified of the segment containing the info. When an info 
segment contains more than one info, any date given in the info heading is used 
as the modification date for that info. help_$init initializes this number to -1, 
indicating that all infos are eligible for selection. 
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sci_ptr 

is a pointer to the subsystem control structure for an ssu invocation. It is used 
by help, to report error messages on behalf of the subsystem. This should be set 
by subsystems which are calling help_ directly. If an sci_ptr exists from a prior 
call to ssu_$create_invocation, then set help_args.sci_ptr to this value. Otherwise, 
after calling help_args_$init, call ssu_$create_standalone_invocation passing it 
help_args.sci_ptr; before calling help_$term, call ssu_$destroy_invocation passing it 
help_args.sci_ptr. 

pad2 

is reserved for future use. This field should not be set or referenced. help_$init 
sets this field to 0. 

search_dirs 

is an array of absolute pathnames specifying directories that help_ will look in 
for named infos. help_ searches for an info unless help_args. path. value contains 
less-than (<) or greater-than (>) characters, or unless 
help_args.path.S.pn_ctl_arg - "l"b. help_$init sets this array to the pathnames 
given for the search list named by its search_list_name argument. The caller can 
change this list before calling help_. Note that the search_dirs are absolute 
pathnames which are expanded from the rules in a search list. If the working 
directory may have changed between calls to help_, then the search list rules must 
be reevaluated before each call to help_. This can be accomplished by calling 
help_$init before each call to help_, and help_$term after each call. 

path 

is an array of minor structures that identify the infos to be printed. 

path, value 

is a value used to select one or more info segments. A relative or absolute 
pathname may be given, or just an entryname. The (final or only) entryname may 
be a starname. A subroutine entry point name may follow the entryname. For 
example: 

ioa_$rsnn1 

or: 

my_i nf o_d i r>extend_subr$ i n i t 

A starname may not be given with a subroutine entry point name or when 
Sctl.ep = "l"b. A proper suffix (as defined by the suffix argument to the help_ 
entry point) is assumed if not given. If path.value contains a less-than or 
greater-than character, it is assumed to be the pathname of an info to be 
printed. Otherwise, path.value is assumed to be the entryname of an info which 
is searched for in directories named in the search_dirs array. Note that path. value 
has a maximum length of 425 characters to accommodate a maximum size 
pathname (168 characters), a maximum size entry point name (256 characters), plus 
a dollar sign ($) separator. 
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path.info_name 

selects an info within the info segments found by path. value. Normally, the caller 
of help_ sets the info_name to a null string, causing help_ to use the (final or 
only) entryname from path. value (without its suffix) as the info_name. help_ then 
searches for an info segment having the info_name (with an appropriate suffix) as 
one of its segment names. help_ looks inside the segment to see if it is divided 
into different information blocks (infos). Lines of the form: 

:lnfo: info_namel: . . . i nf o_nameN: date info_heading 

divide the segment into infos. For each info segment containing multiple infos, 
help_ searches for infos having an info_namei matching the info_name and prints 
only those infos. 

When the caller of help_ gives a nonnull value for path.info_name, then the 
info_name need not be a name on the info segment itself. This is sometimes 
useful for subsystems which want to store all of their infos in a single info 
segment (to reduce storage costs, simplify maintenance of the infos or facilitate 
printing all of the information), but which do not want to add all of the 
info_names to the segment. This avoids the need for many names on the segment, 
and also prevents the system help command from accessing the infos whose names 
do not appear on the info segment. The star convention may be used in the 
path.info_name. Note that the info_namei given in a :Info: line of an info 
segment correspond to names on the info segment when a null path.info_name is 
given. However, when a nonnull path.info_name is given, the info_namei need not 
be unique within the info segment. help_ selects all infos having a matching 
info_namei in the order in which they appear in the info segment, even when 
path.info_name is not a star name. If path.info_name is set to a nonnull value, 
the pathS.info_name_not_starname must also be set 

path.dir 

is the directory part of a pathname given as the value of path, value. help_ sets 
this value, and the caller of help_ need not set this value. The variable is a 
one-dimensional array so that it can be used interchangeably with the search_dirs 
array in searching for info segments. 

path.ent 

is the entryname part of a pathname given as the value of path. value. help_ sets 
this value, and the caller of help_ need not set this value. 

path.ep 

is the entry point name part of a name given in path.value. help_ sets this value, 
and the caller of help_ need not set this value. 
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pathxode 

is a standard status code associated with processing the value given in path. value. 
When help_ returns to its caller with a progress argument value of 3 and a 
nonzero status code argument, the caller of help_ should: examine each path.code; 
for nonzero values, report an error in path. value. path.code may have any of the 
values listed above for the code argument returned by help_ when the progress 
argument is 3. 

path.S 

are flags controlling the interpretation of path, value. 
path.S.pn_ctl_arg 

is "l"b if path.value is to be interpreted as a relative or absolute pathname, 
rather than as an entryname which should be searched for using the search_dirs. 
If the flag is "0"b, then help_ interprets path.value as a pathname only if it 
contains a less-than or greater-than character. The caller of help_ must set this 
flag to the appropriate value. 

path.S.inf o_name_not_starname 

is "l"b if path.info_name is not a star name, even though it may contain * or ? 
characters. A value of "0"b causes path.info_name to be treated as a star name if 
it contains * or ? characters. If the caller sets path.info_name to a nonnull 
value, then this switch must be set 

path.S.less_greater 

is a flag that help_ uses to record that path.value contains less-than or 

greater-than characters, or that path.S.pn_ctl_arg was set The caller of help_ 
need not set this flag. 

path.S.starname_ent 

is a flag that help_ uses to record the fact that the (final or only) entryname in 
path, value is a star name. The caller of help_ need not set this value. 

path.S.starname_inf o_name 

is a flag that help_ uses to record that path.info_name is a star name. The caller 
of help_ need not set this flag. 

path.S.separate_inf o_name 

is a flag that help_ uses to record that path.info_name was supplied by the caller 
of help_, rather than being extracted from path.value by help_. The caller of 
help_ need not set this flag. 

path.S.pad3 

is a reserved field. The caller of help, must set this field to "0"b. 

ca 

is the array of substrings help_ uses in searching for argument or control 
argument descriptions when help_args.Sctl.ca is given. If any of these strings 
appears in the argument name line of an argument or control argument 
description, then help_ prints the entire description. 



11/86 



2-502.1 



AG93-05A 



help_ 



help_ 



sen 

is the array of substrings help_ uses in searching for a matching section title 
when help_args.Sctl.scn is given. All of these substrings must appear (in any 
order) in a matching section title. Comparisons are made after all substrings are 
translated to lowercase, so the letter case of the substrings does not matter. 

srh 

is the array of substrings help_ uses in searching for a matching paragraph when 
help_args.Sctl.srh is. given. All of the substrings must appear (in any order) in a 
matching paragraph. Comparisons are made after all substrings are translated to 
lowercase, so the letter case of substrings does not matter. 

Phelp_args 

is a pointer to the help_args structure. help_$init returns a value for this pointer 

argument. help_, help_$check_info_segs and help_$term require the pointer as an 
input argument. 

I Vhelp_args_2 

is a named constant which the caller of help_$init should use for the 

required_version argument This constant can also be used to check the value of 
help_args. version. 

NOTES 

The structure above is somewhat complex, due to the many options provided by the 
help_ subroutine. Callers of help_ or help_$check_info_segs can use the following 
steps to set structure elements: 

1. Set the Sctl flags to the required values. Set min_Lpgh, max_Lpgh, 
Lspace_between_infos, and min_date_time values if you wish to change the 
defaults supplied by help_$init 

2. If any of the search_dirs are to be set (or changed from the pathnames given in 
the search list named in the call to help_$init), then set Nsearch_dirs to the 
correct value, and set the search_dir array elements to the desired values. 

3. Set Npaths to the number of info pathname /info_name input values. Set the 
elements of help_args.path for each of these input values. If the values are 
arguments in a subsystem help request, they can be placed in the help_args.path 
structure as each argument is processed. In this case, add 1 to Npaths as each 
argument is processed, then set help_args.path(Npaths) to the appropriate input 
values. 

4. Provide substrings used in searching for argument or control argument descriptions, 
if any. Set Ncas to the appropriate value, then store the substrings in the ca 
array. 

5. Provide substrings used in searching for section titles, if any. Set Nscns to the 
appropriate value, then store the substrings in the sen array. 



11/86 



2-502.2 



AG93-05A 



help_ help_ 



6. Provide substrings used in searching for matching paragraphs, if any. Set Nsrhs to 
the appropriate value, then store the substrings in the srh array. 

Note that when substrings for argument and control argument matching, section title 
matching, or paragraph matching are not provided, Ncas, Nscns, or Nsrhs above need 
not be set. help_$init initializes these values to zero. 



Entry: help_$check_iirfo_segs 

This entry point searches for info segments modified since a given date. It returns a 
sorted list of info segments matching the selection criteria. The list is sorted by 
directory name, and within a directory by entryname. In addition, the 
help_$check_info_segs entry point flags entrynames found in more than one directory. 
All but the first such duplicate segment are marked with a cross reference flag and 
are sorted after all unique info segments. The caller provides the selection criteria in 
the help_args structure, obtained by calling help_$init In particular, 
help__args.min_date_time specifies the info segment modification threshold. 

USAGE 

declare help_$check__info_segs entry (char (*) , ptr, char (*) , fixed bin, 
f i xed bin (35) » ptr) ; 

call hel p_$check__i nf o_segs (caller, Phelp__args, suffix, progress, code, 
PPDinfo_seg) ; 

ARGUMENTS 

caller 

is the name of the calling program, on whose behalf the temporary segment 
containing the help_args structure is obtained. (Input) 

Phelps_args 

is a pointer to the help_args structure, described under "Notes" above. (Output) 
suffix 

is the suffix which must appear in the entrynames of info segments to be 
processed by this invocation of help_. This suffix is also assumed when omitted 
from the (final or only) entryname of values given for help_args. path, value in the 
help_args structure (see "Notes" above). If a null string is given, then no suffix is 
required in info segment entrynames, and none is assumed in values of 
help_args.path.value. (Input) 

progress 

is a special status code that indicates which stage of processing help_ was 
performing when an error occurs. (Output) See the help_ entry point 

code 

is a standard status code. (Output) See the help_ entry point 
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PPDinfo_seg 

points to the PDinfo_seg structure, described under "Notes" below. This structure 
contains a sorted list of pointers to descriptors for the selected info segments. 
(Output) 

NOTES 

The PPDinfo_seg argument points to the PDinfo_seg structure that follows. This 
structure is declared in help_cis_args_.incl.pll. All structure values are set by 
help_$check_inf o_segs. 

del 1 PDinfo_seg aligned based (PPD i nfo_seg) , 

2 version fixed bin, 

2 N fixed bin (24) , 

2 P (0 refer (PD i nf o_seg .N) ) 

ptr una 1 , 
PPDinfo_seg ptr, 
VPD i nf o_seg_l fixed bin int static 

opt i ons (constant) init(l); 

Each pointer PDinfo_seg.P points to the following info segment descriptor structure, 
which is also declared in help_cis_args_.incl.pll. 

del 



D i nf o_seg 


al i gned based , 


2 Scross ref 


bi t (36) al i gned, 


2 dir 


char (168) unal , 


2 ent 


char (32) unal , 


2 info_name 


char (32) una 1 ; 


2 ep 


char (32) var , 


2 uid 


bit (36) , 


2 1 


fixed bin (21) , 


2 L 


fixed bin, 


2 date 


f i xed b i n (7 1 ) , 


(2 segment_type 


bit (2) , 


2 mode 


bit (3) , 


2 padl 


bit(3U) unal, 


2 code 


fixed bin (35) ; 



STRUCTURE ELEMENTS 
version 

is the version number of the PDinfo_seg and Dinfo_seg structures (currently 1). 
The variable VPDinfo_seg_l should be used when checking this version number. 



N 



is the number of info segments found. 



is the array of pointers to the Dinfo_seg structures which describe the info 
segments found by the selection criteria. 
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PPDinfo_seg 

is a pointer to the PDinfo_seg structure. 

VPDinfo_seg_l 

is a named constant which the caller of help_$check_info_segs should use when 
testing the value of PDinfo_seg. version. 

Dinfo_seg 

is the structure which describes each info segment found by the selection criteria. 
Scross_ref 

is an info segment cross-reference flag. If the flag equals "l"b, then several info 
segments were found having the same entryname but residing in different 
directories, and the info segment identified by this structure was not the first 
such duplicate. 

dir 

is the directory part of the pathname of the info segment. 



is the final entryname part of the pathname of the info segment. 
info_name 

is reserved for use by help_, and is always a null character string. 

ep 

is the subroutine entry point name given in the selection criteria for the info 
segment. 

uid 

is reserved for use by help_, and is always 0. 

I 

is reserved for use by help_, and is always 0. 

L 

is the length (in characters) of the info segment. 

date 

is the date_time_entry_modified of the info segment. 
segment_type 

is the type of storage system entry identified by Dinfo_seg.dir and Dinfo_seg.ent. 
It may have one of the following values: 
"00"b link 
"01"b segment 

mode 

is the user's access mode to the info segment The three bits correspond to read, 
execute and write access mode. For example, rw access is expressed as "101"b. 



2-504 



AG93-05 



help_ 



help_ 



padl 

is reserved for future use. 

code 

is a standard status code encountered while processing this info segment. It may 

have any of the following values: 

error_table_$noentry 

Dinfo_seg.dir and Dinfo_seg.ent identify a link whose target does not exist. 
error_table_$zero_length_seg 

the info segment is empty. 
error_table_$bad_syntax 

the info segment has a bit count which is not evenly divisible by 9. 

Therefore, the info segment does not contain a whole number of characters. 



Entry: help $init 

This entry point obtains a pointer to the help_args structure (see "Notes" above). This 
structure is used to pass information from the caller to the help_ and help_$check_info_segs 
entry points. The structure is a based structure containing several arrays with 
adjustable extents. The help_$init entry point creates the structure in a temporary 
segment so that these arrays can be grown incrementally by the caller as information 
is added to the structure. 

The help_ subroutine selects and prints info segments based upon the information 
given in the help_args structure. It also uses space in the temporary segment following 
the help_args structure for a work area. For this reason, space for help_args must be 
obtained by calling the help_$init entry point. 

The help_$init entry point obtains the paths defined in a search list named by the 
caller. It stores these paths in the help_args structure for use by the help_ subroutine. 
Several other help_args elements are set, as described under "Notes" above. 

USAGE 

declare help_$init entry (char (*) , char (*) , char (*) , fixed bin, ptr, 
fixed bin (35) ) ; 

call help_$init (caller, searchM i st_name, search_l i st_ref_d i r , 
requi red_version, Phelp_args, code); 
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ARGUMENTS 
caller 

is the name of the calling program, on whose behalf the temporary segment 
containing the help_args structure is obtained. (Input) 

search_list_name 

is the name of the search list to be used in searching for info segments. A null 
string may be given if no search list is to be used. (Input) 

search_list_ref_dir 

is the pathname of the directory to be used when expanding the referencing_dir 
search rule in the search list. If a null string is given, the referencing_dir search 
rule is omitted from the search list. (Input) 

required_version 

is the version number of the help_args structure which the caller is prepared to 
accept. This argument should be set to the value of the Vhelp_args_l constant, 
described under "Notes" above. (Input) 

Phelp_args 

is a pointer to the help_args structure, described under "Notes" above. (Output) 

code 

is a standard status code reporting any failure in expanding the search list. 
(Output) 



Entry: help Sterm 

This entry point releases the temporary segment in which the help_args structure (and 
the POinfo_seg and Dinfo_seg structures of help_$check_info_segs) are created. This 
entry point should be called before calling help_$init again. 

USAGE 

declare help_$term entry (char (*) , ptr, fixed bin (35)); 
call help_$term (caller, Phelp_args, code); 
ARGUMENTS 

The arguments are as described above for the help_ entry point. 
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Name: hphcs_$ips wakeup 

The hphcs_$ips_wakeup entry point sends a specified IPS signal to a specified process. 
That process is interrupted immediately unless it has the specified IPS signal masked 
off. See the description of the hcs_$get_ips_mask, hcs_$reset_ips_mask, and 
hcs$set_ips_mask entry points for a discussion of ips masking. 

USAGE 

declare hphcs_$ i ps_wakeup entry (bit (36) aligned, char (k) aligned); 

call hphcs_$ i ps_wakeup (process_id, ips_name); 

ARGUMENTS 

processed 

is the process identifier of the target process. (Input) 
ips_name 

is the name of the ips signal to be sent to the target process. (Input) 
NOTES 

See the description of the set_ips_mask command for a list of valid ips signal names. 

If the arguments are invalid (nonexistent process, undefined ips signal name) or are 
not properly aligned, the call is ignored; i.e., no signal is sent, and no error indication 

i<: crivpn 



Name: hphcs Sread partition 

This entry point is used to read words of data from a specified disk partition on 
some mounted physical storage system disk. 

USAGE 

del hphcs_$read_par t i t i on entry (bit (36) aligned, char (*) , 

fixed bin (35) > pointer, fixed bin (19) > fixed bin (35) ) I 

call hphcs__$read_par t i t i on (pvid, part i tion_name, offset, data_po i nter , 
word_count, code) ; 
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ARGUMENTS 
pvid 

is the physical volume id of the disk from which to read. (Input). The physical 
volume id is used instead of the volume name because this is a ring zero 
interface, and volume names are not accessible by ring zero; hence, all ring zero 
interfaces that reference physical volumes use the pvid. A pvname can be 
converted to a pvid by a call to mdc_$find_pvname, or the pvid can be obtained 
from find_partition_. 

partition_name 

is the name of the disk partition to be read from. (Input). It must be four 
characters long or shorter. 

offset 

is the offset in words, from the first word of the partition, of the first location 
to be read. (Input). It must be nonnegative and less than the number of words 
in the partition. 

data_ptr 

is a pointer to the user -supplied buffer into which the data is to be read. 
(Input). It must be aligned on a word boundary. 

word_count 

is the number of words to be read. (Input). The sum of offset and word_count 
must be less than or equal to the number of words in the partition. The sum of 
word_count and binary (rel (data_ptr)) must also be less than or equal to 
sys_info$max_seg_size, in order to avoid accessing past the end of the segment 
pointed to by data_ptr. 

code 

is a nonstandard status code. (Output). It can be one of the following: 
0 

indicates that the data was successfully read. 
error_table_$pvid_not_f ound 

indicates that the specified physical volume is not presently mounted. 
error_table_$entry_not_f ound 

indicates that the specified partition could not be found. 
error_table_$out_of_bounds 

indicates that read request attempts to access data outside the partition: that 

is, the sum of offset and word_count is too large, 
an integer between 1 and 10 

indicates that a physical disk error occurred while trying to read the label. 

Error messages for physical disk errors are declared in the include file 

fsdisk_errors.incl.pll, in the array fsdisk_error_message. 
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Name: hphcs Swrite partition 

This entry point is used to write words of data into a specified disk partition on 
some mounted physical storage system disk. No protection is provided against 
simultaneous use of this entry point by several processes writing to the same partition; 
thus, care must be exercised when using it. 

USAGE 

die hphcs_$wr i te_part i tion entry (bit (36) aligned, char (*) , 

fixed bin (35). pointer, fixed bin (18), fixed bin (35) ) *> 

call hphcs_$wr i te_part i tion (pvid, par t i t i on_name, offset, data_poi nter , 
word_count, code) ; 

ARGUMENTS 

pvid 

is the physical volume id of the disk on which to write. (Input). The physical 
volume id is used instead of the volume name because this is a ring zero 
interface, and volume names are not accessible by ring zero; hence, all ring zero 
interfaces that reference physical volumes use the pvid. A pvname can be 
converted to a pvid by a call to mdc_$find_pvname, or the pvid can be obtained 
from find_partition_. 

partition_name 

is the name of the disk partition to be written, (Input). It must be four 
characters long or shorter. 

offset 

is the offset in words, from the first word of the partition, of the first location 
to be written. (Input). It must be nonnegative and less than the number of 
words in the partition. 

data_ptr 

is a pointer to the data which is written into the partition from the user-supplied 
buffer. (Input). It must be aligned on a word boundary. 

word_count 

is the number of words to be written. (Input). The sum of offset and 
word_count must be less than or equal to the number of words in the partition. 
The sum of word_count and binary (rel (data_ptr)) must also be less than or 
equal to sys_info$max_seg_size, in order to avoid accessing past the end of the 
segment pointed to by data_ptr. 
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code 

is a nonstandard status code. (Output). It can be one of the following: 
0 

indicates that the data was successfully written. 
error_table_$pvid_not_found 

indicates that the specified physical volume is not presently mounted. 
error_table_$entry_not_found 

indicates that the specified partition could not be found. 
error_table_$out_of_bounds 

indicates that write request attempts to access data outside the partition; that 

is, the sum of offset and word_count is too large, 
an integer between 1 and 10 

indicates that a physical disk error occurred while trying to read the label. 

Error messages for physical disk errors are declared in the include file 

fsdisk_errors.incl.pll, in the array fsdisk_error_message. 



Name; initiate file 

The initiate_file_ subroutine contains entry points for making a segment or archive 
component known with a null reference name. 

The initiate_file_ entry point, given a directory name, entry name, and access mode, 
checks that the user's process has at least the desired access on the specified segment. 
If so, the segment is initiated with a null reference name. This entry point returns a 
pointer to the base of the segment and the bit count of the segment. 

USAGE 

declare i ni t i ate_f i 1 e_ entry (char (*) , char (*) , bit (*) , pointer, 
fixed binary (24), fixed binary (35)); 

call i ni t i ate_f i 1 e_ (dirname, entryname, mode, seg_ptr, bit_count, 
code) ; 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 



2-510 



AG93-05 



initiate_file_ 



initiate_file_ 



mode 

is the required access mode to the segment. (Input) The first three bits 
correspond to the modes read, execute, and write. The remaining bits, if any, 
must be zero. Named constants for the access modes are declared in 
access_mode_values.incl.pll, and defined in the description of the hcs_$add_acl_en tries 
entry point. 

seg_ptr 

if the segment was made known, this is a pointer to the base of the segment. 
(Output) Otherwise, this is null. 

bit_count 

is the bit count of the segment. (Output) 

code 

is a standard status code. (Output) It may have one of the following values: 
error_table_$no_r_permission 

read permission was required but not present 
. error_table_$no_e_permission 

execute permission was required but not present. 
error_table_$no_w_permission 

write permission was required but not present. 

NOTES 

The specified segment must exist, and the user must have nonnull access to it, as well 
as the required modes, in order to make it known. 

If making the segment known encounters the error_table_$segknown status code, a zero 
status code is returned instead. This enables the user of this entry point to test either 
the returned pointer, or the status code, to indicate whether the segment was made 
known or not. 

The hcs_$terminate_noname entry point or the terminate_file_ subroutine should be 
used to make the segment unknown. 



Entry: initiate file Scomponent 

This entry point can make either a segment or an archive component known with a 
null reference name. 

If the component name is null, this entry point is identical to initiate_file_. 

Otherwise, the directory name and entry name arguments are assumed to specify an 
achive, and the component name specifies a component within that archive. If the 
user's process has at least the desired access on the archive segment, and the user 
desires no more than read access, then the archive is made known with a null 
reference name, and a segment number is assigned. This entry point returns a pointer 
to the base of the component and the bit count of the component. 
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USAGE 

declare i n i t i ate_f i 1 e_$component entry (char (*) , char (*) , char (*) , 
bit (*) , pointer, fixed binary (2k), fixed binary (35)); 

call i n i t i ate_f i 1 e_$ component (dirname, entryname, component_name, mode, 
component_ptr , bit_count, code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

if component_name is null, this is the entryname of the segment. (Input) 
Otherwise, this is the entryname of an archive. The archive suffix must be 
supplied. 

componen t_name 

is null, or is the name of a component in the archive. (Input) 

mode 

is the required access mode to the segment (Input) The first three bits 
correspond to the modes read, execute, and write. The remaining bits, if any, 
must be zero. Named constants for the access modes are declared in 
access_mode_values. inch pi 1 . 

component_ptr 

if the segment was made known, this is a pointer to the base of the segment or 
the base of the archive component. (Output) Otherwise, this is null. 

bit_count 

is the bit count of the segment or archive component. (Output) 

code 

is a standard status code. (Output) In addition to the above values, it can be: 
error_table_$archive_component_modification 

write permission was required on an archive component. 
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NOTES 

The notes for the initiate_file_ entry point apply to this entry point also. 

If a nonnull component name is specified, the following constraints apply to the use 
of this entry point: 

1. The component may not be modified. Only read access is permitted. 

2. The component is guaranteed to be contiguous and aligned on a word boundary. It 

is not guaranteed to have any other alignment. 

3. No explicit dependence on the format of archives is permitted. This means that 

only the data starting at the pointer and extending as far as the bit count may 
be referenced. No data before or after the component may be referenced. 



Entry: initiate file Screate 

This entry point initiates the specified segment with a null reference provided that the 
user's process has at least the desired access to the segment. If the segment does not 
exist, it will be created . 

USAGE 

declare i n i t i ate_f i 1 e_$create entry (char (*) , char (*) , bit (*) , 

pointer, bit (1) aligned, fixed binary (24), fixed binary (35)); 

call i ni t i ate_f i 1 e_$create (dirname, entryname, mode, seg_ptr, created, 
b i t_count , code) ; 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment (Input) 
mode 

is the required access mode to the segment. The first three bits correspond to the 

■mrvrloc ronH avooii fa tir-ri t& TVi/i ramsitiinn Kite 4f Ztr\\7 mi let Vio 70TA TvTpmo/^ 
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constants for the access modes are declared in access_mode_values.incl.pll. (Input) 
seg_ptr 

is set to a pointer to the base of the segment if successful; otherwise, it is set to 
null. (Output) 
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created 

is set to "l"b if the segment did not exist and was created by this call; otherwise, 
it is set to "0"b. (Output) 

bit_count 

is set to the bit count of the segment. (Output) 

code 

is a standard status code. (Output) It can have one of the following values: 
error_table_$no_m_permission 

the segment did not exist and could not be created with the required access. 
error_table_$no_r_permission 

read permission was required but not present. 
error_table_$no_e_permission 

execute permission was required but not present. 
error_table_$no_w_permission 

write permission was required but not present. 
error_table_$moderr 

the user has null access to the segment 

NOTES 

If making the segment known encounters the error_table_$segknown status code, a zero 
status code is returned instead. This enables the user of this entry point to test either 
the returned pointer or the status code to indicate whether the segment was made 
known or not. 



The terminate_file_ subroutine should be used to make the segment unknown. If the 

segment was create by this call and the caller terminates abnormally or its cleanup 

handler is invoked, the caller can use the delete option of terminate_file_ to remove 
the segment that was created. 



Name: interpret resource desc 

The interpret_resource_desc_ subroutine provides a facility for displaying the contents 

of an RCP resource description in a format similar to that used by the resource_status 
command. 

USAGE 

declare i nterpret_resource_desc_ entry (pointer, fixed bin, char (*) , 

bit (36) aligned, bit(l) aligned, char (*) varying, fixed bin (35)); 

call interpret resource_desc (resource desc ptr, nth, callername, 
string (rst_control ) , return_nopr i nt , return_str i ng , code); 
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ARGUMENTS 
resource_desc_ptr 

is a pointer to the structure containing the RCP resource description to be 
displayed. (See the resource_control_ subroutine.) (Input) 

nth 

specifies which element of the resource description is to be displayed (the index 
to the array resource_descriptions.item). If nth is zero, all elements will be 
displayed. (Input) 

callername 

is the name of the command invoking interpret_resource_desc_. It is used in 
printing any necessary error messages. (Input) 

rst_control 

is declared in the include file rst_control.incl.pll. (See "Display Control" below.) 
(Input) 

return_noprint 

specifies, if "0"b, that information about the resource description is to be written 
to the user_output I/O switch. If "l"b, the information is returned in 
return_string, nth must not be zero, and the elements of the structure rst_control 
must be set so that exactly one item of information is requested. (Input) 

return_string 

contains, if return_noprint is "l"b, a printable representation of the information 
requested. Otherwise, its contents are undefined. (Output) 

code 

is a standard status code. (Output) 
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DISPLAY CONTROL 

The rst_control structure (declared in the include file rst_control.incl.pll) is defined as 
follows: 

del 1 rst_control aligned, 



2 


default 


b' 


t 


'1) una! 


gned , 


2 


name 


b 


t 


[]) unal 


gned, 


2 


uid 


b 


t 


[]) unal 


gned, 


2 


potent ial_attributes 


b' 


t 


'1) unal 


gned, 


2 


attr ibutes 


b 


t 


[]) unal 


gned, 


2 


des i red_attr i butes 


b 


t 


[1) unal 


igned, 


2 


potent i a 1 _a i m_range 


b 


t 


[]) unal 


igned, 


2 


a im_range 


b 


t 


'1) unal 


igned, 


2 


owner 


b' 


t 


[1) unal 


igned, 


2 


acs_path 


b" 


t 


[1) unal 


i gned , 


2 


locat i on 


b 


t 


'1) unal 


igned, 


2 


comment 


b 


t 


[1) unal 


igned, 


2 


charge_type 


b 


t 


[1) unal 


igned, 


£. 


mode 


b 


t 


(1) unai 


igned, 


2 


usage_l ock 


b 


t 


[]) unal 


i gned , 


2 


rel ease_l ock 


b 


t 


(1) unal 


igned, 


2 


awa i t i ng_c 1 ear 


b 


t 


[1) unal 
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2 


user_a 1 1 oc 


b 


t 


[1) unal 


i gned , 


2 


g i ven_f 1 ags 


b 


t 


[1) unal 
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2 


mbz 


b 


t 


[16) una 


1 i gned , 


2 


any_g i ven_i tern 


b 


t 


(1) unal 


igned; 



STRUCTURE ELEMENTS 
default 

if "l"b, signifies that certain items of information are to be displayed only if 
they are not in the most common state. This bit should not be used by 
non-system commands. 

name 

is "l"b if item.name is to be displayed. 

uid 

is 'T'b if item.uid is to be displayed. 

potential_attributes 

is "l"b if item.potential_attributes is to be displayed. 

attributes 

is 'T'b if item.attributes is to be displayed. 

desired_attributes 

is "l"b if item.desired_attributes is to be displayed. 
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potential_aim_range 

is "l"b if item.potential_aim_range is to be displayed. 

aim_range 

is "l"b if item.aim_range is to be displayed, 
owner 

is "l"b if item.owner is to be displayed. 
acs_path 

is "l"b if item.acs_path is to be displayed, 
location 

is "l"b if item. location is to be displayed, 
comment 

is "l"b if item. comment is to be displayed. 
charge_type 

is "l"b if i tern. charge_ type is to be displayed, 
mode 

is "l"b if item.mode is to be displayed. 
usage_lock 

is "l"b if item.usage_lock is to be displayed. 
— i 

is "l"b if item.release_lock is to be displayed. 

awaiting_clear 

is "l"b if item.awaiting_clear is to be displayed. 

user_alloc 

is "l"b if item.user_alloc is to be displayed. 
given_flags 

is "l"b if the state of all the flags in the structure item.given is to be displayed. 

mbz 

is unused and must be "0"b. 
any_given_item 

is "l"b to display any field in the item structure for which the corresponding bit 
in the item.given structure is "l"b. 
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The ioa_ subroutine is used for formatting a character string from fixed-point 
numbers, floating-point numbers, character strings, bit strings, and pointers. The 
character string is constructed according to the control characters entered in a "control 
string" and a variable list of arguments that are either edited into the output string in 
character form, or are used in some way to control the formatting of the string. The 
entire procedure is similar to formatted output in PL/ 1 or FORTRAN. 

The ioa_ subroutine has several entry points in order to provide options concerning 
the formatting and disposition of the resulting string. Since any entry point can be 
called with various different arguments, each must be declared (in PL /I) with the 
following attributes: 

declare ioa_ entry options (variable); 
This entry declaration is assumed in all of the entries discussed. 

Calls to the ioa_ subroutine normally append a newline character to the end of the 

JUU15 vivaiwu. 111 viuvi tv i]uy(/iVvKi uuj vnaiavivi, iuv/01 ijr pvo ui 1UQ waild liavv. a 

corresponding entry point with "nnl" (for no newline character); this entry point does 
the same editing. 

Entries: ioa , ioa $nnl 

These two entry points format the input data according to the control string and write 
the resulting string on the user_output I/O switch. 

USAGE 

call ioa_ (control_str i ng , argl, .... argN) ; 

ARGUMENTS 

control_string 

is a character string (char(*) or char(*) varying) of text and control characters 
that determines how the resulting string is to be formed. (Input) 

argl 

are a variable number of arguments (possibly none) that are either edited into the 
resulting string, or used to control the formatting of it. (Input) 
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Entry: ioa__$general_j-s 

This entry point is used to provide the ioa_ subroutine with a control string and 
format arguments taken from a previously created argument list to which a pointer has 
been obtained. 

USAGE 

declare ioa_$general_rs entry (ptr, fixed bin, fixed bin, char (*) , 
fixed bin (21) , bit(l) aligned, bit(l) aligned); 

call ioa_$general_rs (argl i st_ptr , cs_argno, ff__argno, ret_string, len, 
pad_sw, nl_sw) ; 

ARGUMENTS 

arglist_ptr 

is a pointer to the argument list from which the control string and format 
arguments are to be taken. (Input) 

cs_argno 

is the argument number of the control string in the argument list pointed to by 
arglist_ptr. (Input) 

ff_argno 

is the argument number of the first format argument in the argument list pointed 
to by arglist_ptr. (Input) 

ret_string 

contains the formatted string. (Output) It should be large enough to allow for 
expansion. 

len 

specifies the number of significant characters in ret_string. (Output) 
pad_sw 

is a switch to indicate whether the formatted string is padded. (Input) 
"0"b no 
'Tb yes 

nl_sw 

is a switch to indicate whether a newline character is appended to the formatted 
string. (Input) 
u d no 
•Tb yes 
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Entry: ioa $general_rs control string 

This entry point is used to provide the ioa_ subroutine with format arguments taken 
from previously created argument list to which a pointer has been obtained. 

USAGE 

declare ioa_$general_rs_control_str i ng entry (ptr, char (*) , fixed bin 
char (*) , fixed b i n (21) , bit(l) aligned, bit(l) aligned); 

call i oa_$general_rs_control_str i ng (argl i st_ptr , control_str i ng, 
ff_argno, ret__string, len, pad_sw, nl_sw) ; 

ARGUMENTS 

arglist_ptr 

is a pointer to the argument list from which the format arguments are to be 
taken. (Input) 

control_string 

is the control string. (Input) 

ff_argno 

is the argument number of the first format argument in the argument list pointed 
to by arglist_ptr. 

ret_string 

contains the formatted string. (Output) It should be large enough to allow for 
expansion. 

len 

specifies the number of significant characters in ret_string. 
pad_sw 

is a switch to indicate whether the formatted string is padded. (Input) 
"0"b no 
"l"b yes 

nl_sw 

is a switch to indicate whether a newline character is appended to the formatted 
string. (Input) 
"0"b no 
"1" yes 
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Entries: ioa_$ioa__stream, ioa_$ioa_ stream__nnl 

These two entries format the resulting string as above, but the string is then written 
to an I/O switch specified by the switch_name argument in the parameter list. 

USAGE 

call ioa_$ ioa^stream (swi tch_name, control_str i ng, argl, argN) ; 

ARGUMENTS 

switch_name 

is the name of the I/O switch (char(*)) to which the resulting character string is 
to be written. (Input) 

control_string 

is a character string (char(*) or char(*) varying) of text and control characters 
that determines how the resulting string is to be formed. (Input) 

argl 

are a variable number of arguments (possibly none) that are either edited into the 
resulting string, or used to control the formatting of it (Input) 

Entries: ioa $ioa switch, ioa $ioa_switch_ nnl 

These two entry points are identical to the ioa_$ioa_stream and ioa_$ioa_stream_nnl 
entry points except that the I/O switch is specified by a pointer to its control block, 
rather than by name. Since this saves an extra call in the I/O system to locate the 
control block, these calls are more efficient than ioa_$ioa_stream calls. 

USAGE 

call ioa_$ioa_swi tch (iocb_ptr, control_str i ng, argl, argN); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block of the switch. (Input) 
control_string 

is a character string (char(*) or char(*) varying) of text and control characters 
that determines how the resulting string is to be formed. (Input) 

argl 

are a variable number of arguments (possibly none) that are either edited into the 
resulting string, or used to control the formatting of it (Input) 
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Entries: ioa $rs, ioa $rsnnl, ioa Srsnp, ioa_$rsnpnnl 

These entry points edit the resulting string as in the above calls, but instead of being 
written to an I/O switch as the other ioa_ entry points, the string is passed back to 
the caller. The user program must provide a character string variable into which the 
string can be returned. This variable may be varying or nonvarying, aligned or 
unaligned, and of any length. The resulting string is truncated if it exceeds the length 
of the character string provided. 

If the output string is nonvarying, it is padded on the right with spaces if it is not 
completely filled; however, if the call is to either the ioa_$rsnp or ioa_$rsnpnnl entry 
points, the padding is not done. Both the ioa_$rsnnl and ioa_$rsnpnnl entry points 
omit the newline character in the normal way. All of these entry points also return 
the length of the significant data edited into the string. 

USAGE 

call ioa_$rs (control_str i ng, ret_string, len, argl, argN) ; 

ARGUMENTS 

control_string 

is a character string (char(*) or char(*) varying) of text and control characters 
that determines how the resulting string is to be formed. (Input) 

ret_string 

is a string (char(*) or char(*) varying) into which the output string will be edited. 
(Output) 

len 

is the length of the returned string (fixed bin(2D). (Output) 

argl 

are a variable number of arguments (possibly none) that are either edited into the 
resulting string, or used to control the formatting of it. (Input) 

CONTROL STRINGS 

All calls to the ioa_ subroutine require a control_string argument. This is a character 
string consisting of either text to be copied, ioa_ control codes, or both. The control 
codes are always identified by a leading circumflex character (~) . Processing by the 
ioa_ subroutine begins by scanning the control string until a circumflex is found or 
the end of the string is reached. Any text (including any blanks) passed over is then 
copied to the output string. The control code is then interpreted and executed. As a 
rule, this results in the next argument being edited into the output string in some 
character format. The scan then begins again for the next control code. Editing stops 
when the end of the control string is reached. 



2-521 



AG93-05 



ioa_ ioa_ 

The ioa_ subroutine recognizes the following control codes: 

~d ~Nd edit a fixed-point number 

~i ~Ni edit a fixed-point number (same as A d) 

~f ~Nf edit a floating-point number 
~N.Df 

~e ~Ne edit a floating-point number in exponential form 

~o ~No edit a fixed-point number in octal 

~w ~Nw edit a full machine word in octal 

"a ~Na edit a character string in ASCII 

~b ~Nb edit a bit string 
~N.Db 
" . Db 

~A edit an acc string (ALM ASCII with count) 

~P ~Np edit a pointer 

~| | insert formfeed character(s) 

"V ~N/ insert newline character(s) 

~- ~N- insert horizontal tab character(s) 

~x ^Nx insert space character(s) 

insert circumflex character(s) 

~R insert red ribbon shift character 

~B insert black ribbon shift character 

^Ns skip argument(s) 

" ( ~N ( start an iteration loop 

~) end an iteration loop 

start an if /then/else or case selection group 
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limit the scope of a A [ 



~; ~N; used as a clause delimiter between A [ and A ] 

~Nt ^N.Mt insert enough space characters to reach column N 

When N and /or D appear in a control code, they generally refer to a field width or 
a repetition factor, although the exact meaning depends on the control code with 
which they appear (see the detailed explanations that follow). The N or D must be 
specified as unsigned decimal integers, or as the letter "v". If "v" is used, the next 
argument in the argument list is interpreted as a numeric value, and is used to obtain 
the actual value. If this argument happens to be negative or not a number, 0 is 
assumed. 

When no field width is specified, the ioa_ subroutine uses a field large enough to 
contain the data to be edited. If a field size is specified that is too small to contain 
the data, the ioa_ subroutine ignores it and selects a field width of the . appropriate 
size. 

The control codes in the control string must correspond to the types of arguments in 
the argument list. For example, a ^d control code requires a corresponding numeric 
argument. If there is a mismatch between a control code and the type of the 
associated argument, the output for that field is a string of asterisks. 

An invalid control code, an isolated circumflex character (") , or a control code that 
requires an argument that appears after the argument list is exhausted, is inserted into 
the output string unchanged. 

The numeric control codes (~d, "i, ~f , ~e) take any PL/I numeric data type, 
including a character string that represents a numeric value, and use standard PL/ 1 
conversion routines if necessary. (If the argument is complex, only the real part of 
the argument is used.) It should be understood that these control codes, although 
similar to standard PL/ 1 and FORTRAN format codes, do not, in general, give the 
same result. Also, most control codes ignore the field width if the argument is too 
large to fit into the field provided. 

Each of the control codes that result in an argument being edited is explained in 
detail in the following paragraphs. 

~d ~Nd 

takes any numeric argument, including a character string that represents a numeric 
value, and edits it as a decimal integer. If N is not specified, the number is 
printed with no leading spaces or zeros. Negative numbers have a leading minus 
sign. If N is specified, the number is right justified with leading spaces. If the 
number is too large to fit in the specified field width, the field width is ignored. 

is the same as "d, for compatibility with FORTRAN and PL/I formats. 
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~Nf ~N.Df ~.Df 

takes any numeric argument, including a character string that represents a numeric 
value, and edits it as a floating-point number with a decimal point If N is 
omitted, P +/- 1 is assumed, where P is the precision of the argument and the 
extra space is for the decimal point. If the number requires more than N-l 
digits to express, it is edited using ~e format. The value D represents the number 
of digits after the decimal point. If D is omitted, any significant digits after the 
decimal point are printed, with trailing zeros omitted. If D is specified, the 
fractional part of the number is rounded, or padded with extra zeros to achieve 
the desired result. If N is not specified, the number is printed with no leading 
spaces or zeros (except for a zero before the decimal point for numbers less than 
1). If N is specified, the number is right-justified with leading spaces. 

"Ne 

takes any numeric argument, including a character string that represents a numeric 
value, and edits it in floating-point exponential format. The number is always 
left-justified in the field provided, using a standard format. The value N, if 
used, only has meaning if the edited number is less than N characters in length. 
In this case, -The standard format that is always used is: 

N.ddddeN 

The first character is a space for positive numbers, or "-" for negative numbers. 
There is always one digit before the decimal point. The number of digits after 
the decimal point are enough to express the full precision of the argument. 
Trailing zeros in the mantissa are omitted. The exponent sign is omitted if 
positive. Leading zeros in the exponent are also omitted. 

takes a fixed-point binary unsealed argument and edits it in octal. The format is 
the same as explained for ~d. 

"Nw 

takes any argument and edits one machine word in octal. Leading zeros are 
printed. The word is interpreted as an unsigned 36-bit quantity. If N is omitted, 
12 is assumed. If N>12, the number is right- justified with leading spaces. If 
N<12, the ioa_ subroutine attempts to suppress the first 12-N digits. If any of 
these digits are nonzero, the ioa_ subroutine chooses a value of N such that all 
significant digits are printed. 

"Na 

edits a character string in ASCII. Trailing spaces in the argument are ignored. If 
N is specified, the string is left-justified and padded on the right with spaces, to 
make it take up N columns. If the string (without any trailing spaces) is wider 
than N columns, the field width is ignored. If the string contains a newline or 
formfeed, no trailing spaces are ever added. 
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^Nb ~N . Db ~.Db 

assumes bit-string input and converts it to character form. The value D, when 
specified, is the byte size expressed in bits. It may take on only the values 1 
through 4. If D is omitted or less than 1, 1 is assumed. If D is greater than 4, 
4 is assumed. A D of 1 results in the string being output in binary; a D of 2 
results in quarternary (base 4) output; a D of 3 results in octal output; and a D 
of 4 results in hexadecimal output If the field width, N, is omitted, the length 
of the string divided by D is used. If N is specified, the string is truncated on 
the right, or padded on the right with spaces, whichever is appropriate. 



edits an acc string (ALM ASCII with count). The parameter corresponding to the 
should be a pointer to the string. Trailing spaces are not omitted, and no 
field width is accepted. This control code is used to print characters in the ALM 
acc format. 

edits a pointer, entry variable, or label variable in a standard format, as follows: 
sss | ooo (bb) 

where sss is the segment number in octal, ooo is the offset in octal, and bb is 
the bit offset in decimal, all with leading zeros suppressed. If the bit offset is 
zero, the (bb) portion of the pointer is omitted. If a field width is specified, the 
pointer is left justified in a field of width N. 

~Ns 

causes the next argument in the parameter list to be ignored. A ^Ns causes the 
next N arguments to be ignored; ~0s does nothing. If N is greater than or equal 
to the number of arguments remaining, the rest of the argument list is ignored. 

~N ( 

starts an iteration loop, which must be ended by a corresponding ~) . A ~N ( 
specifies that the loop is to be repeated N times. The ~ ( specifies an indefinite 
iteration that is repeated until the argument list is exhausted. A ~0 ( causes 
everything in the control string up to the corresponding to be ignored. 
Iterations may be nested up to four deep. The exact rules under which an 
iteration terminates are explained under ~) . 



marks the end of an interation loop and either terminates the iteration or causes 
it to be repeated, depending on the following rules: 

1. If N is not specified (the iteration is indefinite), then it is only repeated if 
there is something in the control string between the " ( and the that 
requires an argument to be processed (such as ^v/, etc.), AND there 
are arguments remaining that have not been processed. If either of these 
conditions are not met, the loop terminates. 
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2. If N is specified and there is nothing in the control string between the ~N( 
and the that requires an argument to be processed, the iteration is 
repeated until the repetition count is exhausted. If another repetition 
requires an argument, the loop is repeated only if arguments remain to be 
processed, regardless of the value of N. 



starts an if /then /else or case selection group. A ~[ takes a fixed binary or a 
bit-string argument, and must have a matching ~] to limit its scope. Using ~; as 
the delimiter, the text between the ~[ and the ~] may be divided into clauses. 
If ~[ is given a fixed-binary argument of N, the Nth clause between the ~[ and 
the ~] is expanded; all other clauses are ignored. If there is no Nth clause (N 
too large or <D, all the text between the ~[ and the ~] is ignored. If the 
argument to is a nonzero bit string, the first clause is expanded (equivalent to 
a fixed-bin argument of 1 or "then"). If the argument to ~[ is an all-zero bit 
string, the second clause is expanded (the "else" case). The controls may be 
nested up to four deep. Null clauses are permitted. The arguments to *l may 
also be the character strings "true" or "false", which correspond to "l"b and "0"b, 
or a character string containing ASCII digits, which are converted to a fixed 
binary argument. 



limits the scope of a ~L See above. 
~N; 

is used as a clause delimiter between and See above. A ~N; is equivalent 
to N repetitions of 

t ~N.Mt 

inserts enough space characters to reach column N. The column number is 
defined as follows: it is set to 1 when the ioa_ subroutine is entered, and 
whenever a newline character is placed in the output string; it is reduced by 1 
whenever a backspace character is placed in the output string (but it is never 
reduced below 1); it is increased to the next tabstop column (11, 21,...) whenever 
a horizontal tab character is placed in the output string; and it is increased by 1 
when any other character is placed in the output string. If M is specified, it is 
the minimum number of spaces that are to be placed in the output string. The 
default value of M is 1; a value of 0 is permitted. If the current column 
number is greater than N - M, then M spaces are placed in the output string, 
even though this causes the column number to become greater than N. However, 
if the next character string placed in the output string contains leading spaces, 
then ioa_ attempts to force that string into its proper column by deleting enough 
of the leading spaces to counteract the overflow in the previous field. Thus, in 
some cases the desired columnar alignment of data is preserved even when some 
of the data exceed the width of the columns reserved for them. 

ioa_ resets the column count to 0 on each invocation, regardless of whether or 
not the entry point called was a $nnl. This causes ~t to be passing useless with 
any of the ioa_$Xnnl entry points. 
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ARRAY PARAMETERS 

The arguments that are edited into the control string by the ioa_ subroutine may be 
arrays. If this is the case, the ioa_ subroutine selects elements from the array until all 
array elements are used before going to the next argument in the argument list. All 
conventions apply to elements of arrays that apply to simple scalar arguments. In 
particular, the ~s control code skips the next element of an array if the ioa_ 
subroutine is currently in the process of selecting elements from an array. The arrays 
are scanned in the order that PL/I allocates the elements, i.e., row major order. 

EXAMPLES 

The following examples illustrate many, but not all, of the features of the ioa_ 
subroutine. The symbol # is used to represent a space in places where the space is 
significant. 

Source: call ioa_("This is "a the third of ~a" , "Mon" , " Ju 1 y") ; 
Result: This is Mon the third of July 



Source: call ioa_("date ~d/~d/~d, time ~d:~d",6,20,74,20l4,36) ; 
Result: date 6/20/74, time 2014:36 



Source: call i oa_ ("overf 1 ow at ~p",ptr) ; 
Result: overflow at 2 7 1 | 467 1 



Source: call i oa_ ("~2 (~2 (~w ~) " ,wl ,w2 ,w3,w4) ; 

Result: 112233445566OOOO33OO4400 
000000000001 777777777777 



Source: bi t="l 1011 100001 l"b; 

call ioa_("~vxoct=~.3b hex=~.4b",6,bi t,bi t) ; 

Result: ######oct=6703#hex=DC3 



Source: call ioa_("~f ~e ~f ~5.2f ", 1 .0, 1 , le-10, 1) ; 
Resul t: 1 . #1 .e0 #1 .e-10 #1 .00 



Source: call ioa_("~(~d ~) " , 1 , 2 ,56, 1 98, 456 . 7 , 3e6) ; 
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Result: 1 2 56 198 456 3000000 



Source: abs_sw=0; 

call ioa_$rsnnl ('"V (Absentee user ~) "a "a logged out.", 
out_str ,out_cnt,abs_sw,"LeVal ley" , "Shop") ; 

Resu 1 t : out_cnt-25 ; 

out_str="LeVal 1 ey Shop logged out." 



Source: abs_sw=l; /* Using same call to ioa_$rsnnl */ 

call ioa_$rsnnl ("^v (Absentee user ~) ~a logged out.", 
out_str ,out_cnt,abs_sw,"LeVal ley", "Shop") ; 

Resu 1 t : out_cnt=39 ; 

out_str="Absentee user LeValley Shop logged out." 



Source: 
Resul t : 
Source: 
Resul t: 



del a(2,2)fixed bin i ni t (1 , 2 , 3, M ; 
cal 1 ioa_("~d~s "d 'V'.a) ; 

1 3 000000000004 



del b (6: 9) fixed bin i ni t (6,7,8,9) ; 
call ioa_("~v(~3d ~) " .dim (b, 1) ,b) ; 



6 7 8 9 



Source: sw="0"b; 

call ioa_ ("a=~d ~[b=~d~;~s~] c=~d" ,5 , sw, 7 , 9) ; 

Result: a=5 c=9 



Source: sw="l"b; 

call ioa_ ( M a= A d A [b= A d A ; A s A ] c=^d" , 5, sw, 7 , 9) ; 

Result: a=5 b=7 c=9 



Source: dir=">"; ename="foo"; 

call ioa_ ("Error in segment ^a^[>^]^a", dir, 
(dir ~=">") , ename) ; 



Error in segment ^ f go 
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Source: d i r=">f oo" ; ename="bar"; 

call ioa_ ("Error in segment "a"[>"]"a i! , dir, 
(dir ~= ">") , ename) ; 

Result: Error in segment >foo>bar 



Source: option=2; /* Assume following call is on one 1 i ne*/ 
call ioa_ ("Insurance option selected: 

^[no f aul t^bod i 1 y i njury~; property damage^]", option); 

Result: Insurance option selected: bodily injury 

Source: name (1) ="Jones" ; name (2) ="Morganstern" ; name (3) ="Shaughnessey" ; 
amt (1)=59^.27; amt (2) =365.25; amt(3)=1.79; 

do i = 1 to 3; call ioa_ ( ,,/N a~12. lt~6.2f", name (i) , amt (i) ) ; end; 

Result: Jones 59^-27 
Morganstern 3^5 • 25 
Shaughnessey 1.79 



Name: iod info. 



The iod_info_ subroutine extracts information from the I/O daemon tables needed by 
those commands and subroutines that submit I/O daemon requests. 



Entry: iod inf o $dri ver access name 

This entry point returns the driver access name for a specified request type as defined 
in the I/O daemon tables. For example, the driver access name for the "printer" 
request type might be "IO.SysDaemon.*". 

USAGE 

declare i od_i nf o_$dr i ver_access_name entry (char (*) , char (32) , 
fixed bin (35)) ; 

call iod_i nfo_$dr i ver_access_name (request_type, access_name, code); 
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ARGUMENTS 
request_type 

is the name of a request type as defined in the I/O daemon tables. (Input) 
access_name 

is the driver access name for the above request type. (Output) 

code 

is a standard status code. If the specified request type is not found, the code 
error_table_$id_not_found is returned. (Output) 



Entry: iod info Sgeneric type 

This entry point returns the generic type of a specified request type as defined in the 
I/O daemon tables. For example, the generic type for the "unlined" request type 
might be "printer". Refer to the print_request_types command for information on 
generic types available for specific request types. 

USAGE 

declare i od_i nf o_$gener i c__type entry (char (*) , char (32) , fixed bin (35)); 
call i od_i nf o_$gener i c_type (request_type, gener i c_type, code); 
ARGUMENTS 
request_type 

is the name of a request type as defined in the I/O daemon tables. (Input) 
generic_type 

is the name of the generic type of the above request type. (Output) 

code 

is a standard status code. If the specified request type is not found, the code 
error_table_$id_not_found is returned. (Output) 



Entry: iod__info $queue__data 

This entry point examines the I/O daemon tables and returns the default queue and 
maximum number of queues for a given request type. 
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USAGE 

declare i od_i nf o_$queue_data entry (char (*) , fixed bin, fixed bin, 
fixed bin (35) ; 

call iod_i nf o__$queue_data entry (request_type, default_q, max_queues, 
code) ; 

ARGUMENTS 

request_type 

is the name of the request type as defined in the I/O daemon tables. (Input) 
default_q 

is the number of the default queue for the request type. (Output) 
max_queues 

is the number of queues for the request type. (Output) 

code 

is a standard status code. If the specified request type is not found, the code 
error_table_$id_not_found is returned. (Output) 



Entry: iod info Srqt list 

This entry point examines the I/O daemon tables and returns a list of request types 
of a given generic type. 

USAGE 

declare i od_i nf o_$rqt_l i st entry (char (32) , (*) char (32) , fixed bin, 
fixed bin (35)) ; 

call i od_i nf o_$rqt_l i st entry (gen_type, q_ list, n_queues, code); 

ARGUMENTS 

gen.type 

is the generic type of request types to be listed. If the string is blank, then all 
request types are listed. (Input) 
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q_list 

is an array that is filled in with the request type names to be returned. If the 
size of this array is less than the number of names to be returned, the code 
error_table_$too_many_names will be returned, with the partial list. (Output) 

n_queues 

is the number of entries returned in the q_list array. (Output) 

code 

is a standard status code. If there are no matching entries, the code 
error_table_$no_entry is returned. (Output) 



Name: iox 

The iox_ subroutine performs I/O operations and some related functions. I/O 
operations are described in the Programmer's Reference Manual. 

Each entry point documented here has an argument denoting the particular I/O switch 
involved in the operation. For an entry point that requires the I/O switch to be in 
the attached state, the description of the function of the entry point applies only 
when the switch is attached. For other states, see the description of the particular 
I/O module. (The standard system I/O modules are described in Section 3 of this 
document.) 

When an entry point requires the I/O switch to be opened, and it is not open, the 
state of the switch is not changed, and the code error_table_$not_open is returned. If 
the I/O switch is open but the operation is not allowed for that opening mode, the 
state of the switch is not changed, and the code that is returned is 
error_table_$no_operation. 

Operations pertaining to files use four position designators for reference: the next 
byte, the next record, the current record, and the key for insertion. 

Several operations involve the use of a buffer. A buffer is a block of storage 
provided by the caller of the operation as the target for input or the source for 
output. A buffer must be byte aligned; i.e., its bit address and bit length must both 
be evenly divisible by 9. 

The code returned by an entry point may be other than a standard status code in 
cases where the I/O switch is attached via a nonstandard I/O module. All entry 
points in iox_ are declared in the include file iox_dcls.incl.pll. 
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Entry: iox Sattach loud 

This entry point is the same as iox_$attach_ptr except that a call to this entry turns 
on the com_err_ switch of the I/O module. This means that the attach routine of 
the I/O module calls com_err_ when an error is detected. 

USAGE 

declare i ox_$attach_l oud entry (ptr, char (*) , ptr, fixed bin (35)); 

call i ox_$attach_l oud (iocb_ptr , atd, ref_ptr, code); 

ARGUMENTS 

iocb_ptr 

points to the switch's control block. (Input) 

atd 

is the attach description. (Input) 
ref_ptr 

is a pointer to the referencing procedure. It is used by the search rules to find 
an I/O module. (Input) (See hcs_$make_ptr for more information about ref_ptr.) 

code 

is an I/O system status code. 

The code returned by an entry point may be other than a standard status code in 
cases where the I/O switch is attached via a nonstandard I/O module. 



Entry: iox $attach name 

This entry point attaches an I/O switch which is designated by name and returns a 
pointer to its control block. The control block is created if it does not already exist. 
The form of an attach description is given in the Programmer's Reference Manual. If 
the switch is not in the detached state, its state is not changed and the code 
error_table_$not_detached is returned. 

The I/O module is located using the current search rules. 

USAGE 

declare i ox_$attach_name entry (char (*) , ptr, char (*'<) , ptr, 
fixed bin (35)) ; 

call i ox_$attach_name (swi tch_name, iocb_ptr, atd, ref_ptr, code); 
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ARGUMENTS 

switchjiame 

is the name of the I/O switch. (Input) 

iocb_ptr 

points to the switch's control block. (Output) 

atd 

is the attach description. (Input) 
ref_ptr 

is a pointer to the referencing procedure. It is used by the search rules to find 
an I/O module. (Input) ^* vV 

code 

is an I/O system status code. (Output) 



Entry: iox Sattach ptr 

This entry point attaches an I/O switch in accordance with a specified attach 
description. 

USAGE 

declare i ox_$attach_ptr entry (ptr, char («) , ptr, fixed bin (35)); 
call iox_$attach_ptr (iocb_ptr, atd, ref_ptr, code); 
ARGUMENTS 
iocb_ptr 

points to the switch's control block. (Input) 

atd 

is the attach description. (Input) 
ref_ptr 

is a pointer to the referencing procedure. It is used by the search rules to find 
an I/O module. (Input) (See hcs_$make_ptr for more information about ref_ptr.) 

code 

is an I/O system status code. (Output) 
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NOTES 

The ref_ptr argument can be used to specify a particular I/O module if one by that 
name is not already initiated, for example: 

call iox_$attach_ptr (iocb_ptr, "discard_", 

addr (my_d i scard_$my_d i scard_attach) , code); 



Entry: iox Sclose 

This entry point closes an I/O switch. If the switch is not open, its state is not 
changed, and the code error_table_$not_open is returned. 

USAGE 

declare iox_$close entry (ptr, fixed bin (35)); 
call iox_$close (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

points to the switch's control block. (Input) 

code 

is an I/O system status code. (Output) 



Entry: iox Sclose__file 

This entry point closes an I/O switch. If the switch is not open, its state is not 
changed, and the code error_table_$not_open is returned. 



This entry point differs from the iox_$close entry point due to the addition of the 
close description argument. For those I/O modules that support the close_file entry, 
the close description offers a means of providing file closing parameters such as a 
closing comment, where to position to upon closing, etc. 

USAGE 

declare iox_$close_f i le entry (ptr, char (*) , fixed bin (35)); 
call iox_$close_f i le (iocb_ptr, eld, code); 
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ARGUMENTS 
iocb_ptr 

points to the switch's control block. (Input) 

eld 

is the close description, (Input) 

code 

is an I/O system status code. (Output) 



Entry: iox $control 

This entry point performs a specified control order on an I/O switch. The allowed 
control orders depend on the attachment of the switch. If a control order is not 
supported for a particular attachment, the code error_table_$no_operation is returned 
if the switch is open. If the switch is closed, the code error_table_$not_open or 
error_table_$no_operation is returned, the latter code only by I/O modules that 
support orders with the switch closed. For details on control orders, see the 
description of the particular I/O module used in the attach operation. 

USAGE 

declare iox_$control entry (ptr, char (*) , ptr, fixed bin (35)); 
call iox_$control (iocb_ptr, order, info_ptr, code); 
ARGUMENTS 
iocb_ptr 

points to the switch's control block. (Input) 
order 

is the name of the control order. (Input) 
info_ptr 

is null or points to data whose form depends on the I/O module and control 
order. (Input) 

code 

is an I/O system status code. (Output) 
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Entry: iox $delete__record 

This entry point deletes the current record from the file to which an I/O switch is 
attached. The switch must be open for sequential_update, keyed_sequential_update, or 
direct_update. If the current record is null the file's position is not changed, and the 
code error_table_$no_record is returned. 

If the file is open for direct_update and the deletion takes place, the current and 
next record positions are set to null. For keyed_sequential_update, the current and 
next record positions are set to the record following the deleted record or to end of 
file (if there is no such record). 

USAGE 

declare i ox_$del ete_record entry (ptr, fixed bin(35))» 
call iox_$del ete_record (iocb_ptr, code); 
ARGUMENTS 
iocb„ptr 

points to the switch's control block. (Input) 

code 

is an I/O system status code. (Output) 



Entry: iox Sdestroy iocb 

This entry point frees the storage used by the control block for an I/O switch. The 
switch must be in the detached state. Any existing pointers to the control block 
become invalid. 

USAGE 

declare i ox_$destroy_i ocb entry (ptr, fixed bin (35)); 
call iox_$destroy_iocb (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

points to the I/O control block to be freed. (Input) 

code 

is an I/O system status code. (Output) 
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Entry: iox___$detach 

This entry point detaches an I/O switch. If the switch is already detached, its state is 
not changed, and the code error_table_$not_attached is returned. If the switch is 
open, its state is not changed, and the code error_table_$not_closed is returned. 



This entry point differs from the iox_$detach_iocb entry point due to the addition of 
the detach description argument For those I/O modules that support the detach entry, 
the detach description offers a means of providing detach time parameters such as a 
resource disposition comment to be sent to the system operator. 

USAGE 

declare iox_$detach entry (ptr, char (*) , fixed bin (35))*. 

call iox_$detach (iocb_ptr, dtd, code); 

ARGUMENTS 

iocb_ptr 

points to the switch's control block. (Input) 

dtd 

is the detach description. (Input) 

code 

is an I/O system status code. (Output) 



Entry: iox Sdetach iocb 

This entry point detaches an I/O switch. If the switch is already detached, its state is 
not changed, and the code error_table_$not_attached is returned. If the switch is 
open, its state is not changed, and the code error_table_$not_closed is returned. 

USAGE 

declare i ox_$detach_i ocb entry (ptr, fixed (35)) *» 
call iox_$detach_iocb (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

points to the switch's control block. (Input) 

code 

is an I/O system status code. (Output) 
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Entries: iox $err no operation, iox $err not attached, 

iox $err not closed, iox $err not open 

These entry points accept any number of arguments, the last of which is 
fixed bin (35). Each entry point sets the last argument to the respective code; 
error_table_$no_operation, error_table_$not_attached, error_table_$not_closed, or, 
error_table_$not_open. These entry points are assigned to entry variables in the I/O 
control block in order to return an error code when that entry variable is called. See 
the information on user-written I/O modules in the Programmer's Reference Manual 
for instructions on when to assign this entry point to such an entry value. 

USAGE 

declare i ox_$er r_no_operat i on entry options (variable); 
call i ox_$er r_no_operat i on (argl, argN, code); 

ARGUMENTS 
argl 

is a user-supplied argument. (Input) 

code 

is an I/O system status code. (Output) 



Entry: iox_ Sfind _iocb 

This entry point returns a pointer to the control block for an I/O switch. The 
control block is created if it does not already exist. 

USAGE 

declare i ox_$f i nd_i ocb entry (char (*) , ptr, fixed bin (35)); 

call i ox_$f i nd_i ocb (swi tch_name, iocb_ptr, code); 

ARGUMENTS 

switch_name 

is the name of the I/O switch. (Input) 

iocb_ptr 

points to the switch's control block. (Output) 

code 

is an I/O system status code. (Output) 
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NOTES 



If the IOCB is for one of the four standard I/O switches, use one of the four 
standard external static pointers, iox_$user_io, iox_$user_input, iox_$user_output, or 
iox_$error_output. These pointers are declared in iox_dcls.incl.pll. 



Entry: iox Sfind iocb n 

This entry point may be used to find all existing I/O control blocks, whether attached 
or detached. It returns a pointer to the Nth control block in the calling ring, the 
numbering being arbitrary. If there are fewer than N control blocks, a null pointer 
and the code error_table_$no_iocb are returned. Creating or destroying control blocks 
during a sequence of calls to this entry point should be avoided, as it causes 
unpredictable changes to the numbering. 

USAGE 

declare i ox_$f i nd_i ocb_n entry (fixed bin, ptr, fixed bin(35))t 

call iox_$f i nd_iocb_n (n, iocb_ptr, code); 

ARGUMENTS 

n 

is the number of the I/O control block. (Input) 
iocb_ptr 

is a pointer to the control block. (Output) 

code 

is an I/O system status code. (Output) 



Entry: iox $get__chars 

This entry point reads 9-bit bytes from the unstructured file or device to which an 
I/O switch is attached. The switch must be open for stream_input or stream_input_output. 
The desired number of bytes, N, is specified in the call. Some I/O modules may 
actually read fewer than N bytes into the buffer, even though N bytes are available 
from the file or device. In this case the code error_table_$short_record is returned. 
When this code is returned, the caller may again call the iox_$get_chars entry point to 
get more bytes. The contents of the buffer beyond the last byte read are undefined. 

If the switch is attached to a file, bytes are read beginning with the next byte, and 
the next byte position designator is advanced by the number of bytes read. If fewer 
than N bytes remain in the file, the code error_table_$short_record is returned, and 
the next byte position is set to end of file. If the next byte position is already at 
end of file, the code error_table_$end_of_info is returned. 
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It is possible to write a program which takes certain actions if a call to iox_ takes 
longer than a certain amount of time. See the timed_io_$get_chars entry point 

USAGE 

declare i ox_$get_chars entry (ptr, ptr, fixed bi n (21) » fixed bl n (21) , 
fixed bin (35)) ; 

call i ox_$get_chars (iocb_ptr, buff_ptr, n, n_read, code); 

ARGUMENTS 

iocb_ptr 

points to the switch's control block. (Input) 
buff_ptr 

points to the byte-aligned buffer into which bytes are to be read. (Input) 

n 

is the number of bytes to be read where n>=0. (Input) 
n_read 

is the number of bytes actually read. (Output) If code is 0, n_read equals n. 

code 

is an I/O system status code. (Output) 



Entry: iox $get_Jtine 

This entry point reads 9-bit bytes from the unstructured file or device to which an 
I/O switch is attached. The switch must be open for stream_input or stream_input_output. 
Bytes are read until the input buffer is filled, a newline character is read, or end of 
file is reached, whichever occurs first. A code of 0 is returned if and only if a 
newline character is read into the buffer (it will be the last character read). If the 
input buffer is filled without reading a newline character, or if the read operation 
occurred with the input buffer length at zero, the code error_table_$long_record is 
returned. The contents of the buffer beyond the last byte read are undefined. 

If the switch is attached to a file, bytes are read beginning with the next byte, and 
the next byte position designator is advanced by the number of bytes read. If the 
next byte is initially at end of file, the code error_table_$end_of_info is returned. 
Otherwise, if the end of file is reached without reading a newline character, the next 
byte position designator is set to end of file and the code error_table_$short_record is 
returned. 

It is possible to write a program which takes certain actions if a call to iox_ takes 
longer than a certain amount of time. See the timed_io_$get_line entry point. 
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USAGE 

declare i ox_$get_l i ne entry (ptr, ptr, fixed bi n (21) • fixed bl n (21) • 
fixed bin (35)) ; 

call iox__$get_l i ne (iocb_ptr, buff_ptr, buff_len, n_read, code); 

ARGUMENTS 

iocb_ptr 

points to the switch's control block. (Input) 

buff_ptr i\ f b\ 

points to a byte-aligned buffer. (Input) 0>M< \y 

buff Jen 

is the length of the buffer in bytes. (Input) 
n_read 

is the number of bytes read into the buffer. (Output) 

code 

is an I/O system status code. (Output) 



Entry: iox Sinit standard iocbs 

This entry point attaches the standard switches for a user process. These are currently 
user_input, user_output, and error_output, and they are attached with attach descriptions 
of: 

syn_ user_i/o -inhibit close,put_chars 

syn_ user_i/o -inhibit close,get_line,get_chars 

syn_ user_i/o -inhibit close,get_line,get_chars 

The variables iox_$user_input, iox_$user_output, and iox_$error_output are set to the 
iocb pointers for these switches. 

USAGE 

declare i ox_$ i ni t_standard_i ocbs entry (); 

call iox_$ i ni t_standard_i ocbs ; 

NOTES 

Should the standard attachments change, this program will change to establish whatever 
they are. It should therefore be used in any direct process overseer that wishes to 
establish standard attachments. 
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Entry: iox Slook iocb 

This entry point returns a pointer to the control block for a specified I/O switch. If 
the control block does not exist, it is not created, and a null pointer and the code 
error_table_$no_iocb are returned. 

USAGE 

declare i ox__$ 1 ook_i ocb entry (char (*) , ptr, fixed bin (35)); 

call iox_$look_iocb (swi tch_name, iocb_ptr, code); 

ARGUMENTS 

switch_name 

is the name of the I/O switch. (Input) 

iocb_ptr 

is a pointer to the control block. (Output) 

code 

is an I/O system status code. (Output) 



Entry: iox__$modes 

This entry point is used to obtain or set modes that affect the subsequent behavior of 
an I/O switch. The switch must be attached via an I/O module that supports modes. 
If the switch is not attached, the code error_table_$not_attached is returned. If the 
switch is attached, but modes are not supported, the code error_table_$no_operation is 
returned for an open switch and the code error_table_$not_open is returned for a 
closed switch. If the switch is attached and modes are supported, but an invalid mode 
is given, the code error_table_$bad_mode is returned. Each mode is a sequence of 
nonblank characters. A mode string is a sequence of modes, separated by commas and 
containing no blanks. For a list of valid modes, see the particular I/O module 
involved. 

USAGE 

declare iox_$modes entry (ptr, char (*) , char (*) , fixed bin (35)); 
call iox_$modes (iocb_ptr, new_modes, old_modes, code); 
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ARGUMENTS 



iocb_ptr 

points to the switch's control block. (Input) 
new_modes 

is the mode string containing the modes to be set. (Input) Other modes are not 
affected. If this argument is the null string, no modes are changed. 

old_modes 

is the string of modes in force when the call is made. (Output) If this argument 
has length zero, this information is not returned. This argument should be 
declared large enough to accommodate all the modes supported by the I/O 
module; 512 characters should be large enough for all system-supplied I/O 
modules. 

code 

is an I/O system status code. (Output) 



Entry: iox Smove attach 

This entry point moves an attachment from one I/O switch, si, to another I/O 
switch, s2. The si I/O switch must be in the attached state and the s2 switch must 
be in the detached state when the entry point is called. If not, either the code 
error_table_$not_attached (si) or error_table_$not_detached (s2) is returned and no 
change is made to either I/O switch. 

Moving the attachment moves the attach description and open description of the si 
I/O switch to the s2 I/O switch. All pointer values and entry values are copied from 
the control block of the si I/O switch to the control block of the s2 I/O switch. 
Additional information on I/O control blocks is provided in the Programmer's 
Reference Manual. Attach and open data blocks maintained by the I/O module (if 
the si I/O switch is attached) are not affected. Finally, the si I/O switch is set to 
the detached state and iox_$propagate is called for both I/O switches. 

USAGE 

declare i ox_$move_attach entry (ptr, ptr, fixed bin (35)); 
call i ox_$move_at tach (iocb_ptr_l, iocb_ptr_2, code); 
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ARGUMENTS 



iocb_ptr_l 

points to the control block for the I/O switch that is currently attached. (Input) 
This I/O switch is identified as si in the discussion above. 

iocb_ptr_2 

points to the control block for the I/O switch that the user intends to attach. 
(Input) This I/O switch is identified as s2 in the discussion above. 

code 

is an I/O system status code. (Output) 



Entry: iox $open 

This entry point opens an I/O switch. The switch must be attached via an I/O 
module that supports the specified opening mode, and it must be in the closed state. 
If the switch is not attached, its state is not changed, and the code error_table_$not_attached 
is returned. If the switch is already open, the code error_table_$not_closed is 
returned. 

If the switch is attached to a file, the appropriate file position designators are 
established, and an existing file may be replaced by an empty file. This replacement 
may be avoided by specifying extension of the file in the attach description. See the 
information on File Input/ Output in the Programmer's Reference Manual for details. 

declare i ox_$operV (ptr , fixed bin, bit (1) aligned, fixed bin (35)); 

call iox_$open (iocb_ptr, mode, unused, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 
mode 

is the number assigned to the mode, e.g., 1 for stream_input, 2 for stream_output. 
(Input) Numbers associated with all allowed I/O modes are described in the 
Programmer's Reference Manual as part of the information on Input/Output 
Facilities. Named constant values for these modes are defined in iox_modes.incl.pll. 

unused 

must be "0"b. (Input) 

code 

is an I/O system status code. (Output) 
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Entry: iox Sopen file 

This entry point opens an I/O switch. The switch must be attached via an I/O 
module that supports the specified opening mode, and it must be in the closed state. 
If the switch is not attached, its state is not changed, and the code error_table_$not_attached 
is returned. If the switch is already open, the code error_table_$not_closed is 
returned. 



This entry point differs from the iox_$open entry point due to the addition of the 
open description argument. For those I/O modules that support the open_file entry, 
the open description offers a means of providing file opening parameters such as 
format, block size, record size, etc. The open description also allows the logical 
separation of attachment of resources, such as tape volumes, with the iox_$attach_name 
and iox_$attach_ptr entry points, and file specific operations for those I/O modules 
that deal with multi-file resources. 

USAGE 

declare i ox_$open_f i 1 e (ptr, fixed bin, char (*) , bit (1) aligned, 
fixed bin (35)) ; 

call i ox_$open_f i 1 e (iocb_ptr, mode, opd, unused, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 
mode 

is the number assigned to the mode as shown in the Programmers' Reference 
Manual under "Input and Output Facilities". (Output) For example, 1 for 
stream_input, 2 for stream_output. Named constant values for these modes are 
defined in iox_modes.inci.pll. 

opd 

is the open description. (Input) 

unused 

must be "0"b. (Input) 

code 

is an I/O system status code. (Output) 
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Entry: iox $position 

For an I/O switch attached to a file, this entry point positions to the beginning or 
end of the file, or skips forward or backward over a specified number of lines 
(unstructured files) or records (structured files). For an I/O switch attached to a 
device, this operation reads and discards characters until a specified number of newline 
characters have been skipped. 

The switch must be opened in one of the following modes: 

stream_input 

stream_input_output 

sequential_input 

sequential_input_output 

sequential_update 

keyed_sequential_input 

keyed_sequential_update 

In addition, for keyed openings, the next record position should not be null. If it is 
null, the code error_table_$no_record is returned. 

USAGE 

declare i ox_$pos i t i on entry (ptr, fixed bin, fixed bin(21), 
fixed bin (35)) ; 

call iox_$posi tion (iocb_ptr, type, n, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 

type 

identifies the type of positioning. (Input) 
-1 goes to the beginning of the file 
+1 goes to the end of the file 
0 skips newline characters or records 

2 positions to an absolute character or record 

3 skip characters (stream input only) 

n 

is the number of lines, records, or characters to be skipped (forward skip) or the 
negative of that number (backward skip), or the absolute position. (Input) It may 
be 0. 

code 

is an I/O system status code. (Output) 



2-547 



AG93-05 



NOTES 



Absolute positioning moves the next byte or record position to the location specified 
by n. Skipping characters moves the next byte position forward or backward over the 
specified, n, number of characters. If the file contains too few characters, the next 
byte position is at the end of file (forward skip) or beginning of file (backwards 
skip) and error_table_$end_of_info is returned. 

Positioning to the beginning of a nonempty file sets the next record position at the 
first record in the file (sequential and keyed_sequential openings) or sets the next byte 
position at the first byte in the file (stream openings). Positioning to the end of a 
file, or to the beginning of an empty file, sets the relevant position designator to the 
end-of-file position. 

Successively skipping records (sequential and keyed_sequential openings) moves the next 
record position forward or backward by the specified number of records, n, provided 
that many records exist in the indicated direction. For example, suppose that when the 
iox_$position entry point is called, the next record is the mth record in the file, and 
n records are to be skipped. Then for a successful forward skip, the file must contain 
at least (m+n-1) records, and the next record will be set to record (m+n) (if there are 
at least m+n records in the file) or to end of file (if there are m+n-1 or fewer 
records in the file). For a successful backward skip, m must be greater than n, and 
the next record position is set to record (m-n). 

Successively skipping forward over newline characters (stream openings) advances the 
next byte position over the specified number, n, of newline characters, leaving it at 
the byte following the nth newline character or at end of file (if the nth newline 
character is the last byte in the file). Successively skipping backward over n newline 
characters moves the next byte position backward to the nth preceding newline 
character and then moves it further backward as far as is possible without 
encountering another newline character. The effect is to set the next byte position to 
the first character in a line. 

If the relevant part of the file contains too few records or newline characters, the 
next record position or next byte position is set to the first record or byte (backward 
skip with nonempty file) or end of file (all other cases), and the code 
error_table_$end_of_info is returned. 

When a call to the iox_$position entry point specifies skipping zero lines or records, 
the skip is successful, and the next record position is undisturbed. 

In openings for update, the current record position is set to the resulting next record 
or null if the next record is at end of file. 

In the case of keyed_sequential_update, the key for insertion is set to null. 
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Entry: iox Spropagate 

This entry point adjusts certain pointers and entry variables in an I/O control block 
as required when changing between the states detached, attached-closed, and attached-open. 
It also reflects modifications to a control block to other control blocks that are 
synonyms (immediate or chained) for it This entry point must be called at certain 
points in the code of an I/O module, and it must not be called in any other 
circumstances. 

USAGE 

declare i ox_$propagate entry (ptr); 
call i ox_$propagate (iocb_ptr) ; 
ARGUMENTS 
iocb_ptr 

is a pointer to the control block. (Input) 



Entry: iox_$put chars 

This entry point writes a specified number of 9-bit bytes to the unstructured file or 
device to which an I/O switch is attached. The switch must be open for 
stream_output or stream_input_output. 

In the case of a file, if the opening is for stream_output, the bytes are simply added 
at the end of the file. However, if the opening is for stream_input_output, and the 
next byte position is not at end of file, the file is first truncated so that the byte 
preceding the next byte becomes the last byte in the file. The bytes being written are 
then added at the end of the file, and the next byte position is setvto end of file. 

Truncation can be suppressed in storage system files by specifying an appropriate 
attach option. See the description of the vfile_ I/O module in Section 3 for details. 

It is possible to write a program which takes certain actions if a call to iox_ takes 
longer than a certain amount of time. See the timed_io_$put_chars entry point. 

USAGE 

declare i ox_$put_chars entry (ptr, ptr, fixed bin(2i), fixed bin (35)); 

call i ox_$put_chars (iocb_ptr, buff_ptr, n, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 
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buff_ptr 

points to a byte-aligned buffer containing the bytes to be written. (Input) 

n 

is the number of bytes to be written where n>=0. (Input) 

code 

is an I/O system status code. (Output) 



Entry: iox $read__key 

This entry point returns both the key and length of the next record in an indexed 
file attached to an I/O switch. The switch must be open for keyed_sequential_input 
or keyed_sequential_update. If the next record position is at end of file, the code 
error_table_$end_of_info is returned. If the next record position is null, the code 
error_table_$no_record is returned. The next record position is unchanged and the 
current record position is set to the next record if the operation is successful; 
otherwise, the current record position is set to null 

USAGE 

declare i ox_$read_key entry (ptr, char (256) varying, fixed bin(21), 
fixed bin (35) ) ; 

call i ox_$read_key (iocb_ptr, key, rec_len, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 

key 

is the next record's key. (Output) 
rec_len 

is the next record's length in bytes. (Output) 

code 

is an I/O system status code. (Output) 
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Entry: iox Sread length 

This entry point returns the length of the next record in a structured file attached to 
an I/O switch. The switch must be opened in one of the following modes: 

sequential_input 

sequential_input_output 

sequential_update 

keyed_sequential_input 

keyed_sequential_update 

direct_input 

direct_update 

If the next record position is at end of file, the code error_table_$end_of_info is 
returned. If the next record position is null, the code error_table_$no_record is 
returned. The next record position is unchanged and the current record position is set 
to the next record if the operation is successful; otherwise, the current record position 
is set to null. 

USAGE 

declare i ox_$read_l ength entry (ptr, fixed bin(21), fixed bin (35)) » 

call iox_$read_l ength (iocb_ptr, rec_len, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 
rec_len 

is the next record's length in bytes. (Output) 

code 

is an I/O system status code. (Output) 



Entry: iox Sread record 

This entry point reads the next record in a structured file to which an I/O switch is 
attached. The switch must be opened in one of the following modes: 

sequential_input 

sequential_input_output 

sequential_update 

keyed_sequential_input 

keyed_sequential_update 

direct_input 

direct_update 
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The read is successful if the next record position is at a record. If the next record 
position is at end of file, the code error_table_$end_of_info is returned. If the next 
record position is null, the code error_table_$no_record is returned. 

In sequential and keyed_sequential openings, a successful read advances the next record 
position by one record; an unsuccessful read leaves it at the end of file or null. In 
direct openings, this operation always sets the next record position to null. In openings 
for update, a successful read sets the current record position to the record just read; 
an unsuccessful read sets it to null. In openings for keyed_sequential_update and 
direct_update, the key for insertion is always set to null. 

If the record is too long for the specified buffer, the first part of the record is read 
into the buffer, and the code error_table_$long_record is returned. As far as setting 
position indicators is concerned, this is considered a successful read. In all cases, the 
contents of the buffer beyond the last byte read are undefined. 

USAGE 

declare i ox_$read_record entry (ptr, ptr, fixed bin(21), fixed bin(21), 
fixed bin (35)) : 

call iox_$read_record (iocb_ptr, buff_ptr, buff_len, rec_len, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 
buff_ptr 

points to a byte-aligned buffer into which the record is to be read. (Input) 
buffjen 

is the length of the buffer in bytes. (Input) 
rec_len 

is the length of the record in bytes. (Output) 

code 

is an I/O system status code. (Output) 
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Entry: iox_$rewrite record 

This entry point replaces the current record in a structured file to which an I/O 
switch is attached. The switch must be open for sequential_update, keyed_sequential_update, 
or direct_update. If the current record position is null, the code error_table_$no_record 
is returned. 

For keyed_sequential_update and sequential_update, this operation sets the next record 
position to the record immediately following the current record or to end of file (if 
no such record exists). (It is possible that the next record position may already be at 
this point). For direct_update, the next record position is set to null. No other 
changes are made to the position designators. 

USAGE 

declare iox_$rewr i te_record entry (ptr, ptr, fixed bin(21), 
fixed bin (35)) 5 

call i ox_$rewr i te_record (iocb_ptr, buff_ptr, rec_len, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 
buff_ptr 

points to a byte-aligned buffer containing the new record. (Input) 
recjen 

is the length of the new record. (Input) 

code 

is an I/O system status code. (Output) 



Entry: iox Sseek key 

This entry point searches for a record with a given key in an indexed file to which 
an I/O switch is attached. It also serves to define the key for a record to be added 
by a following write_record operation. The switch must be opened in one of the 
following modes: 

keyed_sequential_input 

keyed_sequential_output 

keyed_sequential_update 

direct_input 

direct_output 

direct_update 
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For keyed_sequential_output, the given key should be greater (according to the rules 
for character-string comparison) than the key of the last record in the file. If it is, 
the code error_table_$no_record is returned, and the key for insertion is set to the 
given key. Otherwise, the code error_table_$key_order is returned, and the key for 
insertion is set to null. 

For other openings, this entry point performs as follows: 

1. If the file contains a record with the given key, a code of 0 is returned, 

the record's length is returned, the next record position and current record 
position are set to the record, and the key for insertion is set to null. (Not 
all of these position designators are applicable in all openings.) 

2. If the file does not contain a record with the given key, the code 

error_table_$no_record is returned, the next record position and current record 
position are set to null, and the key for insertion is set to the given key. 
(Not all of these position designators are applicable in all openings.) 

USAGE 

declare i ox_$seek_key entry (ptr, char (256) varying, fixed bin (21), 
fixed bin (35)) ; 

call i ox_$seek_key (iocb_ptr, key, rec_len, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 

key 

contains the given key. (Input) All trailing blanks are removed from key to 
obtain the given key, and the result may be the null string. 

rec_len 

is the length in bytes of the record with the given key. (Output) 

code 

is an I/O system status code. (Output) 
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Entry: iox $write record 

This entry point adds a record to a structured file to which an I/O switch is 
attached. The switch must be opened in one of the following modes: 

sequential_output 

sequential_update 

sequential_input_output 

keyed_sequential_output 

keyed_sequential_update 

direct_output 

direct_update 

If the switch is open for sequential_output, the record is added at the end of the 
file. If the switch is open for sequential_input_output, and the next record position is 
not at the end of the file, the file is truncated so that the record preceding the next 
record becomes the last record in the file. The new record is then added at the end 
of the file. 

Truncation can be suppressed in sequential__input_output, and write operations can be 
performed in sequential_update openings of storage system files. See the description of 
the vfile_ I/O module for details. 

If the switch is open for keyed_sequential_output, keyed_sequential_update, direct_output, 
or direct_update, the key for insertion designator should designate a key. If it does 
not, the code error_table_$no_key is returned and nothing is changed. If there is a 
key for insertion, the new record is added to the file with that key and the key for 
insertion is set to null. For keyed_sequentiai_update, and sequen tiai_update, the next 
record position is set to the record immediately following the new record or to end 
of file (if there is no such record). For keyed_sequential_update, sequen tial_update, 
and direct_update, the current record position is set to the new record. 

USAGE 

declare i ox__$wr i te_record entry (ptr, ptr, fixed bin (21), 
fixed bin (35)) ; 

call iox_$wr i te_record (iocb_ptr, buff_ptr, rec_len, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to the control block. (Input) 
buff_ptr 

points to a byte-aligned buffer containing the new record. (Input) 
rec_len 

is the length of the new record in bytes. (Input) 



2-555 



AG93-05 



code 

is an I/O system status code. (Output) 



Name: ipc 

The Multics system supports an interprocess communication facility. The basic purpose 
of the facility is to provide control communication (by means of stop and go signals) 
between processes. 

The ipc_ subroutine is the user's interface to the Multics interprocess communication 
facility. Briefly, that facility works as follows: a process establishes event channels in 
the current protection ring and waits for an event on one or more channels. 

Event channels can be thought of as numbered slots in the interprocess communication 
facility tables. Each channel is either an event-wait or event-call channel. An 
event-wait channel receives events that are merely marked as having occurred and 
awakens the process if it is blocked waiting for an event on that channel. On an 
event-call channel, the occurrence of an event causes a specified procedure to be 
called if (or when) the process is blocked waiting for an event on any channel. 
Naturally, the specific event channel must be made known to the process that expected 
to notice the event. For an event to be noticed by an explicitly cooperating process, 
the event channel identifier value is typically placed in a known location of a shared 
segment. For an event to be noticed by a system module, a subroutine call is typically 
made to the appropriate system module. A process can go blocked waiting for an 
event to occur or can explicitly check to see if it has occurred. If an event occurs 
before the target process goes blocked, then it is immediately awakened when it does 
go blocked. 

The user can operate on an event channel only if his ring of execution is the same as 
his ring when the event channel was created (for a discussion of rings see the 
Programmer's Reference Manual.) 

The hcs_$wakeup entry point is used to wake up a blocked process for a specified 
event. 



Entry: ipc $block 

This entry point blocks the user's process until one or more of a specified list of 
events has occurred. 

USAGE 

declare ipc_$block entry (ptr, ptr, fixed bin (35)); 

ca)l ipc_$block (event_wa i t_l i st_ptr . event_wa i t_i nf o_ptr , code); 
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ARGUMENTS 
event_wait_list_ptr 

is a pointer to a structure that specifies the channels on which events are being 

awaited. (Input) This structure is declared in event_wait_list.incl.pll. 

del 1 event_wai t_l i st based aligned (event_wai t_1 i st_ptr) , 
2 r_channels fixed bin, 

2 pad bit (36) , 

2 channel__id (event_wa i t__l i st__n_channel s refer 

(event_wai t_J i st .n_channel s) ) fixed bin (71); 

STRUCTURE ELEMENTS 
n_channels 

is the number of channels. This item must be allocated on an even-word 
boundary. 

pad 

must be zero, 
channeled 

is an array of channel identifiers selecting the channels to wait on. 

Frequently ipc_$block is called with only one channel in the wait list In this case, 
the following structure may be used. It is declared in event_wait_channel.incl.pll. 

del 1 event_wai t_channel aligned, 

2 n_channels fixed bin initial (1), 

2 pad bit (36) , 

2 channel_id (1) fixed bi n (71) ; 

where: 

event_wait_inf o_ptr 

is a pointer to a structure into which the ipc_$block entry point can put 
information about the event that caused it to return (i.e., that awakened the 
process). This structure is declared in event_wait_info.incl.pll. (Input) 

del 1 event_wai t_i nfo based aligned (event_wa i t_i nf o_ptr) , 

2 channel__id fixed bi n (7 1) • 

2 message fixed bin (71), 

2 sender bit (36) , 
2 origin, 

3 dev_signal bit ( 1 8) unaligned, 

3 ring fixed b i n (1 7) unaligned, 

2 channel index fixed bin; 
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STRUCTURE ELEMENTS 
channel_id 

is the identification of the event channel, 
message 

is an event message as specified to the hcs_$wakeup entry point, 
sender 

is the process identifier of the sending process. 
dev_signal 

indicates whether this event occurred as the result of an I/O interrupt. 
"l"b yes 
"0"b no 

ring 

is the sender's validation level. 
channel_index 

is the index of channeled in the event_wait_list structure above. 

code 

is a standard status code. (Output) 



Entry: ipc Screate event channel 

This entry point creates an event channel of the specified type with the specified 
parameters. This entry replaces the ipc_$create_ev_chn and ipc_$decl_event_call_chn 
sequence to create normal call channels. This entry is the only way to create an async 
event call channel. 

USAGE 

del i pc_$create_event_channel entry (ptr, fixed bin (71) , 
fixed bin (35)) ; 

call i pc_$create_event_channel (arg_ptr, channeled, code); 

ARGUMENTS 

arg_ptr 

is a pointer to ipc_create_arg_structure described below. (Input) 
channeled 

is the identifier of the event channel created. (Output) 

code 

is a standard system status code. (Output) 
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NOTES 

The following structure contains the arguments to the create_event_channel entry. All 
of the fields of the structure are to be filled in on input The structure is declared 
in ipc_create_arg.incl.pll: 

del 1 i pc_create_arg_structure aligned 

based (ipc_create_arg_structure_ptr) , 
2 version char (8) unaligned, 

2 channel_type fixed bin, 

2 call_entry variable entry (ptr), 

2 cal l_data_ptr ptr, 
2 cal l_pr ior i ty fixed bin (17); 



STRUCTURE ELEMENTS 



version 

is the version of the structure. It should be set to the constant: 
ipc_create_arg_structure_vl. (Input) 

channel_type 

is the type of event channel that is to be created. Constant values for the type 
can be found in event_channel_types.incl.pll as follows: (Input) 

1 FAST_EVENT_CHANNEL_TYPE 

2 WAIT_EVENT_CHANNEL_TYPE 

3 CALL_EVENT_CHANNEL_TYPE 

4 ASYNC_CALL_EVENT_CH ANNEL.TYPE • 

call_entry 

is the procedure entry point invoked when an event occurs on the specified 
channel. (Input) 

call_data_ptr 

is a pointer to data to be passed to and interpreted by the procedure entry point. 
(Input) 

call_priority 

is a number indicating the priority of an event call channel as compared to other 
event call channels declared by this process for this ring. If, upon interrogating 
all the appropriate event call channels, more than one is found to have received 
an event, the lowest-numbered priority is honored first, and so on. Synchronous 
and asynchronous call channels are the same with respect to this priority. (Input) 
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Entry: ipc $cutoff 

This entry point inhibits the reading of events on a specified event channel. Any 
pending events are not affected. More can be received, but do not cause the process 
to wake up. 

USAGE 

declare ipc_$cutoff entry (fixed bin(7D» fixed bin(35))» 

call ipc__$cutoff (channeled, code); 

ARGUMENTS 

channeled 

is the identifier of the event channel. (Input) 

code 

is a standard status code. (Output) 

T7_* : <pj 1 . — i* ~i 
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This entry point changes an event-call channel into an event-wait channel. 
USAGE 

declare i pc_$dec l_ev__wa i t_chn entry (fixed bin (71). fixed bin(35))» 

call i pc_$dec l_ev_wa i t_chn (channel_id, code); 

ARGUMENTS 

channel_id 

is the identifier of the event channel. (Input) 

code 

is a standard status code. (Output) 
Entry: ipc Sdelete ev chn 

This entry point destroys an event channel previously created by the process. 
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USAGE 

declare i pc_$de 1 ete_ev_chn entry (fixed bin (71) , fixed bin (35) ) < 

call ipc_$de1ete_ev_chn (channeled, code); 

ARGUMENTS 

channeUd 

is the identifier of the event channel. (Input) 

code 

is a standard status code. (Output) 
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Entry: ipc Sdrain chn 

This entry point resets an event channel so that any pending events (i.e., events that 
have been received but not processed for that channel) are removed. 

USAGE 

declare i pc_$dra i n_chn entry (fixed b i n (7 1 ) • fixed bin(35))» 

call i pc_$dra i n_chn (channel_id, code); 

ARGUMENTS 

channeled 

is the identifier of the event channel. (Input) 

code 

is a standard status code. (Output) 
Entry: ipc $mask ev calls 

This entry point causes the ipc_$block entry point to completely ignore event-calls 
occurring in the user's ring at the time of this call. This call causes a mask counter 
to be incremented. Event calls are masked if this counter is greater than zero. 

USAGE 

declare i pc_$mask_ev_cal 1 s entry (fixed bin (35)); 

call i pc_$mask_ev_ca 11 s (code); 

ARGUMENTS 

code 

is a standard status code. (Output) 
Entry: ipc $read ev chn 

This entry point reads the information about an event on a specified channel if the 
event has occurred. 

USAGE 

declare i pc_$read_ev_chn entry (fixed b i n (7 1 ) , fixed bin, ptr, 
fixed bin (35)) ; 

call i pc_$read_ev_chn (channel_id, ev_occurred, event_wa i t_i nf o_ptr , 
code) ; 
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ARGUMENTS 
channel_id 

is the identifier of the event channel. (Input) 
ev_occurred 

indicates whether an event occurred on the specified channel. (Output) 

0 no event occurred 

1 an event occurred 

event_wait_inf o_ptr 

is a pointer to a structure into which the ipc_$block entry point can put 

information about the event that caused it to return (i.e., that awakened the 
process). This structure is declared in event_wait_info.incl.pll. (Input) See the 
description in the ipc_$block entry point 

code 

is a standard status code. (Output) 



Entry: ipc Sreconnect 

This entry point enables the reading of events on a specified event channel for which 
reading had previously been inhibited (using the ipc_$cutoff entry point). All pending 
signals, whether received before or during the time reading was inhibited, are 
henceforth available for reading. 

USAGE 

declare i pc_$reconnect entry (fixed bin(71), fixed bin (35)); 

call i pc_$reconnect (channel_id, code); 

ARGUMENTS 

channel_id 

is the identifier of the event channel. (Input) 

code 

is a standard status code. (Output) 
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Entry: ipc_$set__call prior 

This entry point causes event-call channels to be given priority over event-wait 
channels when several channels are being interrogated; e.g., upon return from being 
blocked and waiting on any of a list of channels. Only event channels in the current 
ring are affected. By default, event-call channels have priority. 

USAGE 

declare i pc_$set_ca 1 l_pr i or entry (fixed bin (35)); 

call i pc_$set_cal l_pr ior (code); 

ARGUMENTS 

code 

is a standard status code. (Output) 
Entry: ipc $set wait prior 

This entry point causes event-wait channels to be given priority over event-call 
channels when several channels are being interrogated; e.g., when a process returns 
from being blocked and is waiting on any of a list of channels. Only event channels 
in the current ring are affected. 

USAGE 

declare i pc_$set_wa i t_pr i or entry (fixed bin (35)); 

call i pc_$set_wa i t_pr i or (code); 

ARGUMENTS 

code 

is a standard status code. (Output) 
Entry: ipc $ unmask ev calls 

This entry point causes the event-call mask counter to be decremented. Event calls 
remain masked as long as the counter is greater than zero. To force event calls to 
become unmasked, call this entry point repeatedly, until a nonzero code is returned. 

USAGE 

declare i pc_$unmask_ev_cal 1 s entry (fixed bin (35)); 
call i pc_$unmask_ev_ca 1 1 s (code); 
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ARGUMENTS 
code 

is a standard status code. A nonzero code is returned if event calls were not 
masked at the time of the call. (Output) 

INVOKING AN EVENT-CALL PROCEDURE 

When a process is awakened on an event-call channel, control is immediately passed to 
the procedure specified by the ipc_$decl_event_call_channel entry point. The procedure 
is called with one argument, a pointer to the following structure. This structure is 
declared in event_call_info.incl.pll. 

del 1 event_cal l_i nf o based aligned (event_cal l_i nf o_ptr) , 
2 channel_id fixed bin(7D, 

2 message fixed bin (71), 

2 sender bit (36) , 

2 or i g i n, 

3 dev_signal bit ( 1 8) unaligned, 

3 ring fixed bin (17) unaligned, 

2 data_ptr ptr; 

STRUCTURE ELEMENTS 

channeled 

is the identifier of the event channel. 

message 

is an event message as specified to the hcs_$wakeup entry point, 
sender 

is the process identifier of the sending process. 
dev_signal 

indicates whether the event occurred as the result of an I/O interrupt. 
"l"b yes 
"0"b no 

ring 

is the sender's validation level. 
data_ptr 

points to further data to be used by the called procedure. 
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Name: lex__string__ 

The lex_string_ subroutine provides a facility for parsing an ASCII character string 
into tokens (character strings delimited by break characters) and statements (groups of 
tokens). It supports the parsing of comments and quoted strings. It parses an entire 
character string during one invocation, creating a chain of descriptors for the tokens 
and statements in a temporary segment The. cost per token of lex_string_ is 
significantly lower than that of parse_file_ because the overhead of calling parse_file_ 
to obtain each token is eliminated. Therefore, the lex_string_ subroutine is recommended 
for translators that deal with moderate to large amounts of input 

The descriptors generated when the lex_string_ subroutine parses a character string can 
be used as input to translators generated by the reductions command, as well as in | 
other applications. In addition, the information in the statement and token descriptors 
can be used in error messages printed by the lex_error_ subroutine. 

Refer to the the reductions and lex_error_ descriptions for details on the use of these | 
facilities. 



Entry: lex string $init_Jex delims 

This entry point constructs two character strings from the set of break characters and 
comment quoting, and statement delimiters: one string contains the first character of 
every delimiter or break character defined by the language to be parsed; the second 
string contains a character of control information for each character in the first 
string. These two character strings form the break tables that the lex_string_ 
subroutine uses to parse an input string. It is intended that these two (delimiter and 
control) character strings be internal static variables of the program that calls 
lex_string_, and that they be initialized only once per process. They can then be used 
in successive calls to iex_string_$lex, as described below. 

USAGE 

declare lex_str ing_$ini t_lex_del ims entry (char (*) , char (*) , char (*) , 
char (*) , char (*) , bit(*), char (*) varying aligned, 
char (*) varying aligned, char (*) varying aligned, 
char (*) varying aligned); 

call lex_str ing_$ini t__lex_del ims (quote_open, quo te__c lose, comment_open, 
comment_close, statement_del im, Sinit, break_chars, 
i gnored_break_chars, lex_delims, 1 ex_contro1_chars) ; 
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max_severity_no 

is the severity number (fixed bin) of the highest severity error message that has 
been printed by the lex_error_ subroutine. (Input/Output). Before the lex_error_ 
is invoked by a translator, max_severity_no should be initialized to 0. Each time 
it is called, the lex_error_ subroutine compares this value with the severity_no of 
the current message and sets max_severity_no to the higher of these two numbers. 

Pstmt 

is a pointer to the statement descriptor generated by the lex_string_ subroutine 
for the statement that is to be printed after the error message. (Input). The line 
number and statement number given in this statement descriptor are included in 
the error message. 

Ptoken 

is a pointer to the token descriptor of the token that is in error. (Input). If 
Pstmt is null, then the number of the line that contains the token described by 
the descriptor is included in the error message. If both Pstmt and Ptoken are 
null, then no line number is included in the error message. 

Scontrol 

is a control bit string (bit(*)) that determines whether the message character string 
or the brief_message character string is used in the error message. (Input). The 
interpretation of the bits in this string is described in "Notes" below. 

error_message_text 

is an ioa_ control string (char(*) or char(*) varying) that contains the long form 
of the error message text (Input) 

brief_message_text 

is an ioa_ control string (char(*) or char(*) varying) that contains the brief form 
of the error message text. (Input) 

argN 

are optional arguments that are substituted into the ioa_ message texts, in place of 
the ioa_ control characters. (Input) 
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NOTES 

The error messages that are generated by the lex_error_ subroutine have the form 
shown below. 

prefix error_number, SEVERITY sever i ty_no IN STATEMENT k OF LINE 1. 

er ror_message_text 

SOURCE: 

statement_i n_error 
For example, 

ERROR 7, SEVERITY 2 IN STATEMENT 2 OF LINE 2. 

A bad track specification was given in a Volume statement. 

9track has been assumed. 

SOURCE: 

Volume: 70082, 8 track; 

The severity_no associated with an error controls the prefix that is placed in the error 
message, as shown in the list below. 



0 COMMENT 

Comment. The error message is a comment, which does not indicate that an error 
has occurred, but merely provides information for the user. 

1 WARNING 

Warning only. The error message warns of a statement that may or may not be 
in error, but compilation continues without ill effect. 

2 ERROR 

Correctable error. The message diagnoses an error that the translator can correct, 
probably without ill effect. Compilation continues, but correct results cannot be 
guaranteed. 

3 FATAL ERROR 

An uncorrectable but recoverable error. The translator has detected an error that 
it cannot correct. Translation continues in an attempt to diagnose further errors, 
but no output is produced by the translation. 

4 TRANSLATOR ERROR 

An unrecoverable error. The translator cannot continue beyond this error. The 
translation is aborted after the error message is printed. 
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The phrase "IN STATEMENT k OF LINE 1" appears in the error message only if 
Pstmt is a nonnull pointer. Pstmt is assumed to point to a statement descriptor 
generated by the lex_string_ subroutine. The values for k and 1 come from this 
descriptor. If the error occurred in the first statement of line 1, then the phrase 
"STATEMENT k OF" is omitted from the error message. 

If Pstmt is null, then "STATEMENT k OF" is omitted from the error message, and 1 
is the line number on which the token described by Ptoken appears. If Ptoken is a 
null pointer, "IN STATEMENT k OF LINE 1" is omitted altogether. 

Currently, only the first two bits of the Scontrol bit string have meaning, as shown in 
the table below. 

Scontrol I nterpretation 

"00"b The printed error contains the error_message_text the first time the error 
occurs, and the brief _message_text for subsequent occurrences of that 
error during a given translation. 

"10"b The printed error always contains the error_message_text. 

"ll"b The printed error always contains the error_message_text. 

"01"b The printed error always contains the brief_message_text. 

If Serror_printed is "l"b, then the lex_error_ subroutine assumes the text of the error 
message has already been printed in a previous message. It uses the long or brief 
error message text, according to the value of Scontrol. 

If Pstmt points to a statement descriptor, then the lex_error_ subroutine sets the 
error_in_stmt switch in the statement descriptor. It also checks the value of the 
output_in_err_msg switch in the descriptor. If this switch is "0"b, the lex_error_ 
subroutine sets it to "l"b and prints the character string representation of the 
statement in the error message. If it is already "l"b, then the lex_error_ subroutine 
assumes that the statement has already appeared in another error message and omits 
the "SOURCE:" phrase from the error message. 

If max_severity_no is less than severity_no, then the lex_error_ subroutine sets 
max_severity_no equal to severity _no. 

Refer to the lex_string_ subroutine for a description of statement' and token 
descriptors. 
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NOTES 

A user should be familiar with interprocess communication in Multics and the pitfalls 
of writing programs that can run asynchronously within a process. For example, if a 
program does run asynchronously within a process and it does input or output with 
the tty_ I/O module, then the program should issue the start control order of tty_ 
before it returns. This is necessary because a wakeup from tty_ may be intercepted 
by the asynchronous program. 

If a program establishes an event-call channel, and the procedure associated with the 
event-call channel uses static storage, then the event-call procedure should have the 
perprocess_static attribute. This is not necessary if the procedure is part of a limited 
subsystem in which run units cannot be used. See the description of the run command 
in the Commands manual for more information on run units and perprocess_static. 



Name: lex_error 

The lex_error_ subroutine generates compiler-style error messages on the error_output 
I/O switch for translators generated by the reductions command and for other | 
procedures that process tokens generated by the lex_string_ subroutine. See "Notes" | 
below for a description of the error message format 1 

USAGE 

declare lex_error_ entry options (variable); 

call lex_error_ (error_number , Serror_pr i nted, sever ity_no, 

max_sever i ty_no, Pstmt, Ptoken, Scontrol , message, br i ef_message, 
argl , . . . , argN) ; 

ARGUMENTS 

error_number 

is the error number (fixed bin), as it should appear in the error message. (Input) 
Serror_printed 

is a switch (bit(l) unaligned) that is "l"b if the text of the error message has 
been printed in a previous error and "0"b, otherwise. (Input/Output). If 
Serror_printed is "l"b, the text is omitted from the error message. Otherwise, text 
is included and the switch is set to "l"b to suppress this text in any subsequent 
occurrence of the same error. 

severity_no 

is the severity number (fixed bin) of the error. (Input). It must have a value 

from 0 through 4. See "Notes" below for an interpretation of the severity_no 
value. 
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ARGUMENTS 
quote_open 

is the character string delimiter that begins a quoted string. (Input). It can 
contain up to four characters. If it is a null character string, then quoted strings 
are not supported during the parsing of an input string. 

quote_close 

is the character string delimiter that ends a quoted string. (Input). It can be the 
same character string as quote_open, and can contain up to four characters. 

comment_open 

is the character string delimiter that begins a comment (Input). It can contain 
up to four characters. If it is a null character string, then comments are not 
supported during the parsing of a character string. 

comment_close 

is the character string delimiter that ends a comment. (Input). It can be the 
same character string as comment_open, and can contain up to four characters. 

statement_delim 

is the character string delimiter that ends a statement. (Input). It can contain up 
to four characters. If it is a null character string, then statements are not 
delimited during the parsing of a character string. 

Sinit 

is a bit string that controls the creation of statement descriptors, and the creation 
of token descriptors for quoting delimiters. (Input). The bit string consists of two 
bits in the order listed below. 

Ssuppress_quoting_delims 

is "l"b if token descriptors for the quote opening and closing delimiters of a 
quoted string are to be suppressed. A token descriptor is still created for the 
quoted string itself, and the quoted_string switch in this descriptor is turned 
on. If Ssuppress_quoting_delims is "0"b, then token descriptors are returned 
for the quote opening and closing delimiters, as well as for the quoted string. 

Ssuppress_stmt_delims 

is "l"b if the token descriptor for a statement delimiter is to be suppressed. 
The end_of_stmt switch in the descriptor of the token that precedes the 
statement delimiter is turned on, instead. If Ssuppress_stmt_delims is "0"b, 
then a token descriptor is returned for a statement delimiter, and the 
end_of_stmt switch in this descriptor is turned on. 
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break_chars 

is a character string containing all of the characters that can be used to delimit 
tokens. (Input). The string can include characters used also in the quoting, 
comment, or statement delimiters, and should include any ASCII control characters 
that are to be treated as delimiters. 

ignored_break_chars 

is a character string containing all of the break_chars that can be used to delimit 
tokens but that are not tokens themselves. (Input). No token descriptors are 
created for these characters. 

lex_delims 

is an output character string containing all of the delimiters that the lex_string_ 
subroutine uses to parse an input string. (Output). This string is constructed by 
the init_lex_delims entry from the preceding arguments. It must be long enough 
to contain all of the break_chars, plus the first character of the quote_open 
delimiter, the comment_open delimiter, and the statement_delim delimiter, plus 30 
additional characters. This length must not exceed 128 characters, the number of 
characters in the ASCII character set. 

lex_control_chars 

an output character string containing one character of control information for 

each character in lex_delims. (Output). This string is also constructed by 

init_lex_delims from the preceding arguments. It must be as long as lex_delims. 



Entry: lex string $lex 

This entry point parses an input string, according to the delimiters, break characters, 
and control information given as its arguments. The input string consists of two parts: 
the first part is a set of characters, which are to be ignored by the parser except for 
the counting of lines; the second part is the characters to be parsed. It is necessary 
to count lines in the part that is otherwise ignored so that accurate line numbers can 
be stored in the token and statement descriptors for the parsed section of the string. 

USAGE 

declare 1 ex_str i ng_$ 1 ex entry (ptr, fixed bin(21), fixed bin(21), ptr, 
bi t (*) , char (*) , char (*) , char (*) , char (*) , char (*) , 
char ('0 varying aligned, char (*) varying aligned, 
char (*) varying aligned, char (*) varying aligned, ptr, ptr, 
fixed bin (35)) ? 

call 1 ex_str i ng_$ 1 ex entry (Pinput, Linput, L i gnored_i nput , Psegment, 
SI ex, quote_open, quote_close, comment_open, comment_close, 
statement_del im, break_chars, i gnored_break_chars , 1 ex_del ims, 
1 ex_control_chars, Pf i rst_stmt_desc, Pf i rst_token_desc , code); 
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ARGUMENTS 
Pinput 

is a pointer to the string to be parsed. (Input) 
Linput 

is the length (in characters) of the second part of the input string, the part that 
is actually to be parsed. (Input) 

Lignored_input 

is the length (in characters) of the first part of the input string, the part that is 
ignored except for line counting. (Input). This length can be 0 if none of the 
input characters are to be ignored. 

Psegment 

is a pointer to a temporary segment created by the translator_temp_ subroutine. 
(Input) 



SLex 



AO U. Wifc JU H15 WIUL WU11U V1J U1W V1W1UU11 V/l JtUtWlllWX L U11U VV/llliliWll L UWVl IJSlX/l Oj 

the handling of doubled quotes within a quoted string, and the interpretation of a 
comment_close delimiter that equals the statement_delim. (Input). The bit string 
consists of four bits in the order listed below. 

Sstatement_desc 

is "l"b if statement descriptors are to be created along with the token 
descriptors. If Sstatement_desc is "0"b, or if the statement delimiter is a null 
character string, then no statement descriptors are created. 

Sscomment_desc 

is "l"b if comment descriptors are to be created for any comments that 
appear in the input string. When Scomment_desc is "0"b, comment_open is a 
null character string, or statement descriptors are not being created, then no 
comment descriptors are created. 

Sretain_doubled_quotes 

is "l"b if doubled quote_close delimiters that appear within a quoted string 
are to be retained. If Sretain_doubled_quotes is "0"b, then a copy of each 
quoted string containing doubled quote_close delimiters is created in the 
temporary segment with all doubled quote_close delimiters changed to single 
quote_close delimiters. 

Sequate_comment_close_stmt_delim 

is "l"b if the comment_close and statement_delim character strings are the 
same, and if the closing of a comment is to be treated as the ending of the 
statement containing the comment. It could be used when parsing line-oriented 
languages that have only one statement per line and one comment per 
statement. 
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quote_open 

is the character string delimiter that begins a quoted string. (Input). It can 
contain up to four characters. If it is a null character string, then quoted strings 
are not supported during the parsing of an input string. 

quote_close 

is the character string delimiter that ends a quoted string. (Input). It can be the 
same character string as quote_open, and can contain up to four characters. 

comment_open 

is the character string delimiter that begins a comment (Input). It can contain 
up to four characters. If it is a null character string, then comments are not 
supported during the parsing of a character string. 

comment_close 

is the character string delimiter that ends a comment. (Input). It can be the 
same character string as comment_open, and can contain up to four characters. 

statement_delim 

is the character string delimiter that ends a statement. (Input). It can contain up 
to four characters. If it is a null character string, then statements are not 
delimited during the parsing of a character string. 

break_chars 

is a character string containing all of the characters that can be used to delimit 
tokens. (Input). The string can include characters used also in the quoting, 
comment, or statement delimiters, and should include any ASCII control characters 
that are to be treated as delimiters. 

ignored_break_chars 

is a character string containing all of the break_chars that can be used to delimit 
tokens but that are not tokens themselves. (Input). No token descriptors are 
created for these characters. 

lex_delims 

is the character string initialized by lex_string_$init_lex_delims. (Input) 
lex_control_chars 

is the character string initialized by lex_string_$init_lex_delims. (Input) 
Pfirst_stmt_desc 

is a pointer to the first in the chain of statement descriptors. (Output). This is a 
null pointer on return if no statement descriptors have been created. 

Pf irst_token_desc 

is a pointer to the first in the chain of token descriptors. (Output). This is a 
null pointer on return if no tokens were found in the input string. 
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code 

is one of the following status codes: (Output) 
0 

the parsing was completed successfully. 
error_table_$zero_length_seg 

no tokens were found in the input string. 
error_table„$no„stmt„delim 

the input string did not end with a statement delimiter, when statement 

delimiters were used in the parsing. 
error_table_$unbalanced_quotes 

the input string ended with a quoted string that was not terminated by a 

quote_close delimiter. 

NOTES 

Any character can be used in the quoting, comment, and statement delimiter character 
strings, including such characters as new line and the space character. A quoted string 
is defined in the PL/ 1 sense, as a string of characters that is treated as a single 
token, even though some of the characters can be delimiters or break characters. The 
string must begin with a quote_open delimiter, and must end with a qucte_ close 
delimiter. Two consecutive quote_close delimiters can be used to represent a 
quote_close delimiter within the quoted string. The lex_string_$lex entry point provides 
the option of retaining any doubled quote_close delimiters in the quoted string token, 
or of copying the quoted string into the temporary segment, changing double 
quote_close to single quote_close delimiters, and treating the modified copy as the 
quoted string token. Switches in the token descriptor of a quoted string are turned 
on: to indicate that the token is a quoted string; to indicate whether any quote_close 
delimiters appear within the quoted string; and to indicate whether doubled quote_close 
delimiters have been retained in the token. 

Statements are defined as groups of tokens that are terminated by a statement 
delimiter token. The lex_string_$lex subroutine can optionally return a token descriptor 
for the statement delimiter or it can suppress the token descriptor of the statement 
delimiter. It always turns on the end_of_stmt switch in the final token descriptor of 
each statement, even if the token descriptor of the statement delimiter has been 
suppressed. Besides, it can optionally return a statement descriptor that points to the 
descriptors for the first and last tokens of a statement, contains a pointer to and the 
length of the part of the input string containing the entire statement, and describes 
various other characteristics of the statement. These descriptors are described in the 
next section. 

Comments are defined in the PL/ 1 sense, as a string of characters that begin with a 
comment_open delimiter, and that end with a comment_close delimiter. Comments that 
appear in the input string act as breaks between tokens. The lex_string_$lex entry 
point can optionally create descriptors for each comment that appears in a statement. 
These descriptors are chained off of the statement descriptor for that statement. 
Switches are set in each comment descriptor of a given statement to indicate whether 
the comment appears before any of the tokens in that statement, and whether any 
tokens intervene between this comment and any previous comments in that statement. 
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The lex_string_ subroutine uses the translator_temp_ facility to allocate space for the 
descriptors in the temporary segment. Refer to the translator_temp_ subroutine 
description for details on the use of these temporary segments. 

DESCRIPTORS 

If the lex_string_$lex entry point were invoked using standard PL/ 1 parsing 

conventions to parse the input shown below, then tokens and token descriptors created 
by the lex_string_ subroutine would have the following form: 

Volume: 70092; 
Wr i te; 

File 4; /* Process hth file on the tape. */ 

/* END */ 
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--> 
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v 

Vo 1 ume 



v 

70092 



v 

Wr i te 



v 

Fi le 



If statement descriptors were being created by the lex_string_ subroutine, then the 
output would have the following form: 




vvvvvvvvv 
Volume : 70092 ; Write ; File k 
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Below is a declaration for the token descriptor structure: 



del 1 token 

2 groupl 
3 version 
3 size 
2 Pnext 
2 Plast 
2 Pvalue 
2 Lvalue 
2 Pstmt 
2 Psemant 
2 group2 

3 I token_i n_stmt 
3 1 i ne_no 
3 Nvalue 
3 S, 

4 end_of_stmt 
4 quoted_str i ng 
h quotes_i n_str i ng 
h quotes_doubl ed 
h pad2 



aligned based (Ptoken) , 

unal i gned, 

f i xed bi n (17) , 

fixed bin(17) , 

ptr unal , 

ptr unal, 

ptr unal , 

fixed bin (18) , 

ptr unal , 

ptr unal, 

unal i gned, 

f i xed bi n (17) , 

f ixed bin (17) , 

f i xed bin (35) » 

bit(l) , 

bit (1) , 
bi t (1) , 
bit (1) , 
bit (32) ; 



del 
del 



Ptoken 
token value 



ptr; 

char (token. Lvalue) based (token. Pvalue) ; 



STRUCTURE ELEMENTS 
version 

is the version number of the structure. The structure shown above is version 1. 



size 



is the size of the structure, in words. 



Pnext 



is a pointer to the descriptor for the next token in the input. If this is the last 
token descriptor, then the pointer is null. 



Plast 



is a pointer to the descriptor for the previous token in the input. If this is the 
first token descriptor, then the pointer is null. 



Pvalue 

is a pointer to the token character string. 



Lvalue 

is the length of the token character string, in characters. 
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Pstmt 

is a pointer to the statement descriptor for the statement that contains this token. 
If statement descriptors are not being created, then this pointer is null. 

Psemant 

is a pointer available for use by the caller of lex_string_. It is initialized as a 
null pointer. It might be used to chain a structure defining the semantic value of 
the token to the token's descriptor. 

Itoken_in_stmt 

is the position of the token with respect to the other tokens in the statement 
containing this token. If no statement delimiters are being used in the parsing, 
then this is the position of the token with respect to all other tokens in the 
input. 

line_no 

is the line_no on which this token appears. 
Nvalue 

is a number available for use by the caller of lex_string_. It is initialized to 0. 
It might be set to the numeric value of a token that is the character string 
representation of an integer. 

end_of_stmt 

is "l"b if this is the last token of a statement 
quoted_string 

is "l"b if this token appeared in the input as a quoted string. 
quotes_in_string 

is "l"b is quote_close delimiters appear within this quoted string token. 
quotes_doubled 

is 'T'b if quote_close delimiters that appear in a quoted string token are still 
represented by doubled quote_close delimiters, rather than having been converted 
to single quote_close delimiters. 

pad2 

is available for use by the caller of lex_string_. It is initialized to ""b by 
lex„string_. 

Ptoken 

is a pointer to a token descriptor. 
token_value 

is the character string representation of the token described by the token 
descriptor pointed to by Ptoken. 
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Statement descriptors are declared by the structure shown below. 



del 1 stmt 

2 groupl 

3 version 

3 size 
2 Pnext 
2 Plast 
2 Pvalue 
2 Lvalue 
2 Pfirst_token 
2 Plast_token 
2 Pcomments 
2 Puser 
2 group2 

3 Ntokens 

3 1 i ne_no 

3 I stmt in 1 i ne 



semant_type 
~> * 

4 error_i n_stmt 

k output_i n_err_msg 

k pad 



al igned based (Pstmt) , 

unal i gned, 

f i xed bi n (17) , 

f i xed bi n (1 7) , 

ptr unal , 

ptr unal , 

ptr unal , 

fixed bin(l8) , 

ptr unal , 

ptr unal , 

ptr unal , 

ptr unal , 

unal igned, 

fixed bin (17) , 

fixed bin (17) , 

fixed bin (17) , 

f ixed bin (17) » 

bit (1) , 
bit(l) , 
bit (3*0 ; 



del Pstmt 

del stmt value 



ptr; 

char (stmt. Lvalue) based (stmt .Pvalue) ; 



STRUCTURE ELEMENTS 
version 

is the version number of this structure. The structure declared above is version 1. 



size 



is the size of this structure, in words. 



Pnext 



is a pointer to the statement descriptor for the next statement. If this is the 
descriptor for the last statement, then this pointer is null. 



Plast 

is a pointer to the descriptor for the previous statement. If this is the descriptor 
for the first statement, then the pointer is null. 

Pvalue 

is a pointer to the character string representation of the statement as it appears 
in the input, excluding any leading newline characters or leading comments. 



Lvalue 

is the length of the character string representation of the statement, in characters. 
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Pfirst_token 

is a pointer to the descriptor of the first token in the statement 
Plast_token 

is a pointer to the descriptor of the last token in the statement 
Pcomments 

is a pointer to a chain of comment descriptors associated with this statement. 
Puser 

is a pointer available for use by the caller of lex_string_. 
Ntokens 

is a count of the tokens in this statement 
line_no 

is the line number on which the first token of this statement appears in the 
input 

semant_type 

is a number available for use by the caller of lex_string_. It is initialized to 0 
by lex_string_. It might be used to classify the statement by its semantic type. 

error_in_stmt 

is "l"b if an error has occurred while processing this statement. This switch is 
never set by lex_string_, but it is set by lex_error_ when a statement descriptor 
is used to generate an error message. 

output_in_err_msg 

is *T'b if the statement has already been output in another error message. This 
switch is referenced and set by lex_error_ to prevent a statement from being 
printed in more than one error message. 

pad 

is available for use by the caller of lex_string L _. It is initialized to ""b by 
lex_string_. 

Pstmt 

is a pointer to a statement descriptor. 
stmt_value 

is the character string value of the statement, as it appears in the input, excluding 
any leading newline characters or leading comments. 
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Comment descriptors are declared as follows. 



del 1 comment 



2 groupl 
3 version 
3 size 



aligned based (Pcomment) , 
unal i gned, 
fixed bin (17) , 
f i xed b i n (17) , 



2 Pnext 
2 Plast 
2 Pvalue 
2 Lvalue 



fixed bin(l8) , 
una 1 i gned 
f ixed bin (17) , 



ptr unal , 
ptr unal, 
ptr unal , 



2 group2 
3 1 i ne_no 
3 S, 



h before_stmt 
k contiguous 
k pad 



bit(l) , 
bit(l) , 
bit (16) ; 



del Pcomment 

del comment value 



ptr; 

char (comment. Lvalue) based (comment . Pva 1 ue) ; 



STRUCTURE ELEMENTS 
version 

is the version number of this structure. The structure declared above is version 1. 

size 

is the size of this structure, in words. 
Pnext 

is a pointer to the descriptor for the next comment associated with the statement 
containing this comment If there are no more comments associated with that 
statement, then the pointer is null. 



is a pointer to the descriptor for the previous comment associated with the 
statement containing this comment. If this is the first comment associated with 
the statement, then the pointer is null. 



is a pointer to the character string value of the comment string, exactly as it 
appears in the input, excluding the comment_open and comment_close delimiters. 

Lvalue 

is the length of the character string value of the comment, in characters. 
line_no 

is the line number on which the comment begins. 
before_stmt 

is "l"b if the comment appears in its statement before any tokens. 



Plast 



Pvalue 
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contiguous 

is "l"b if no tokens appear between this comment and the previous comment 
associated with this statement. 

pad 

is available for use by lex_string_'s caller. 
Pcomment 

is a pointer to a comment descriptor structure. 

comment_value 

is the character string value of a comment 

The above declarations are available for inclusion in PL/ 1 programs in 
lex_descriptors_.incl.pll. 



Name: list dir info 

The list_dir_info_ subroutine is used by the list_dir_info, rebuild_dir, and comp_dir_info 

commands to list the values in a single entry in a directory information segment 
created by the save_dir_info command. 

USAGE 

declare I i st_d i r_i nf o_ entry (ptr, fixed bin, char(l)); 

call 1 i st_di r_i nf o_ (ptr, mode, prefix); 

ARGUMENTS 

Ptr 

points to an entry in the dir_info segment (created by invoking the save_dir_info 
command). (Input) 

mode 

is the verbosity desired. (Input). It can be 0, 1, or 2 (where 0 is the least 
verbose). 

prefix 

is a one-character prefix for every line printed. (Input) 
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NOTES 

Output from the list_dir_info_ subroutine is written on the user_output I/O switch. It 
consists of a series of lines, each of the form: 

item name: value 



The prefix character is appended to the beginning of each line. 

The list below gives the output items for each verbosity level, for segments, 
directories, and links. Verbosity level 1 returns information listed in 0 and 1; 
verbosity level two returns information listed in 0, 1, and 2. 



For segments: 

0. names 
type 

date used 
date mod i f i ed 



1. date branch modified 
records used 
bit count 
bit count author 
max length 
safety switch 
property 1 i st 



2. ACL 

data dumped 
current length 
device ID 
move device !D 
copy switch 
ring brackets 
unique ID 
author 



For directories: 

0 . names 
type 

date used 
date mod i f i ed 



date branch modified 
bit count 
records used 
quota 

date dumped 
current length 
device ID 
move device ID 
copy switch 
ring brackets 
unique ID 
author 

bit count author 
max length 
safety switch 
property 1 i st 



2. ACL 

initial seg ACL 
initial d i r ACL 



For links: 



names 

type 

target 



date 1 I nk mod i f i ed 



2 . date 1 I nk dumped 
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Name: match__star_name_ 

The match_star_name_ subroutine implements the Multics star convention by comparing 
an entryname with a name which may contain stars or question marks, called a 
starname. 

USAGE 

declare match_star_name =- entry (char (*) , char (*) , fixed bin(35))» 

call match_star_name_ (entryname, starname, code); 

ARGUMENTS 

entryname 

is the string to be compared with the starname. Trailing spaces in this string are 
ignored. (Input) 

starname 

is the string with which the entryname is compared. Trailing spaces in this string 
are ignored. (Input) 

code 

is one of the standard status codes listed below. (Output) 
LIST OF STATUS CODES 
0 

the entryname matches the starname. 

error_table_$nomatch 

the entryname does not match the starname. 

error_table_$badstar 

the starname does not have an acceptable format 

NOTES 

See the description of the hcs_$star_ entrypoint in hcs_ to find how to list the 
directory entries that match a given starname. See check_star_name_ to find how to 
validate a starname. See starname.gi.info for the rules governing the formation and 
interpretation of starnames. 
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Name: mdc 

The mdc_ subroutine (actually a ring 1 gate) provides a series of entry points for 
manipulation of master directories. 

Entry: mdc Scheck mounted 

This entry point determines whether a logical volume is mounted and available for use. 
USAGE 

declare mdc_$check_mounted entry (char (*) , fixed bin(35))> 

call mdc_$check_mounted (lv_name, code); 

ARGUMENTS 

lv_name 

is the name of the logical volume. (Input) 

code 

is a standard system status code. (Output) Its possible values are: 
0 

the volume is mounted and ready for use. This does not mean it is attached 
to the calling process (see Notes, below.) 

error_table_$mount_not_ready 
the volume is not mounted. 

NOTES 

Use hcs_$lv_attached to determine if a logical volume is both mounted and attached 
to the calling process. 

ACCESS REQUIRED 

No special access is required. 
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Entry: mdc $create__ dir 

This entry point is used to create a new master directory. Its arguments are roughly 
analogous to the hcs_$append_branchx entry point. 

USAGE 

declare mdc_$create_.di r entry (char (*) , char (*) , char (*) , 

bit (36) aligned, (3) fixed bin (3), char (*) , fixed bin, 
fixed bin(35)) ; 

call mdc_$create_di r (dir_name, entryname, volume, mode, rings, user_Jd, 
quota, code) ; 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the subdirectory. (Input) 
volume 

is the name of the logical volume that is to contain segments created in the new 
directory. (Input) 

mode 

is the user's access mode. (Input) 
rings 

are the ring brackets of the directory. (Input) Only the first values are used. 
user_id 

is an access control name. (Input) 
quota 

is the quota to be placed on the new directory. (Input) 

code 

is a standard status code. (Output) 
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Entry: mdc_$create dirx 

This entry point is an extension of the mdc_$create_dir entry point, which is similiar 
to hcs_$create_branch_ entry point. 

USAGE 

declare mdc Screate dirx entry (char (*) , char (*) , char (*) , ptr, 
f ixed"bin(35)F; 

call mdc_$create_di rx (dir_name, entryname, volume, info_ptr, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the subdirectory. (Input) 
volume 

is the name of the logical volume that is to contain segments created in the new 
directory. (Input) 

info_ptr 

is a pointer to the create_branch_info structure as described under the 
hcs_$create_branch_ entry point. (Input) 



Entry: mdc__$delete__dir 

This entry point is used to delete a master directory. 
USAGE 

declare mdc_$del ete_d i r entry (char (>'<) , char (*) , fixed bin (35)) I 

call mdc_$del ete_di r (dir_name, entryname, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the subdirectory. (Input) 
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code 

is a standard status code. (Output) 



Entry: mdc_$find_lvid 

This entry point returns the logical volume identifier for a given logical volume name. 
USAGE 

declare mdc_$f i nd_l vid entry (char (*) , b i t (36) , fixed bin (35)); 

call mdc_$f i nd_l vid (1v_name, lvid, code); 

ARGUMENTS 

lvname 

is the logical volume name whose identifier is to be returned. (Output) 

lvid 

is a logical volume identifier. (Input) 

code 

is a standard status code. (Output) 



Entry: mdc_$get lv access 

This entry point gets the calling process' effective access to manipulate a logical 
volume. 

USAGE 

declare mdc_$get_l v_access entry (char (*) , fixed bin (3). fixed bin (5), 
bit (1) aligned, fixed bin (35) ) » 

call mdc_$get_l v_access (1v_name, ring, mode, public, code); 

ARGUMENTS 

lv„name 

is the logical volume name. (Input) 

ring 

is the validation level for which access is to be calculated. (Input) 
mode 

is either REW_ACCESS_BIN for a volume executive, RW_ACCESS_BIN for a user 
with access to use the volume, or N_ACCESS_BIN for a user with no access to 
the volume. (Output) These values are declared in access_mode_values.incl.pll. 
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public 

is *T'b if the volume is public. 

code 

is a standard system status code. (Output) 
ACCESS REQUIRED 
No special access is required. 



Entry: mdc $pvname info 

This entry point gets various kinds of information about a specified storage-system 
physical volume. 

USAGE 

declare mdc_$pvname_i nf o entry (char (*) , bit (36) aligned, char (*) , 
bit (36) aligned, fixed bin, fixed bin (35)); 

call mdc_$pvname_i nf o (pvname, pvid, lvname, lvid, devi ce_type, code); 

ARGUMENTS 

pvname 

is the name of the physical volume about which information is to be returned. 
(Input) 

pvid 

is the physical volume id of the specified volume. It can be used as a parameter 
to ring-zero volume and partition interfaces. (Output) 

lvname 

is the name of the logical volume to which the physical volume belongs. (Output) 

lvid 

is the logical volume id of the logical volume to which the physical volume 
belongs. (Output) 

device_type 

is a number indicating what type of device the specified physical volume is 
mounted on. The names and characteristics of these devices are listed in various 
arrays declared in the include file fs_dev_types.incl.pll. (Output) 

code 

is a standard system-status code. It is nonzero if the information about the 
volume cannot be obtained or if the volume does not exist. (Output) 
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Entry: mdc„,$set_mdir_account 

This entry point is used to set the quota account of a master directory. 
USAGE 

declare mdc $set mdir account entry (char (*) , char (*) , char (*) , 
fixed~bin(35))-;~ 

call mdc_$setjndi r_account (dir_name, entryname, account, code); 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the subdirectory. (Input) 
account 

is the name of the new quota account The directory quota is returned to the old 
account and redrawn from this new account. 

code 

is a standard system status code. (Output) 



Entry: mdc $set mdir owner 

This entry point is used to set the owner name of a master directory. 
USAGE 

declare mdc_$set_mdi r_owner entry (char (*) , char («) , char (*) , 
fixed bin (35)) ; 

call mdc_$set_md i r_owner (dir_name, entryname, owner, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the subdirectory. (Input) 
owner 

is the new owner name of the master directory, in the form Person_id.Project_id.tag. 
(Input) 

code 

is a standard system status code. (Output) 
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Entry: mdc $set mdir_quota 

This entry point is used to set the quota on a master directory. 
USAGE 

declare mdc_$set_md i r_quota entry (char (*) , char (*) , bit(l) aligned, 
fixed bin, fixed bin (35)); 

call mdc_$set_md i r_quota (dir_name, entryname, sw, quota, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the subdirectory. (Input) 



is a switch indicating the kind of quota change. (Input) 

"0"b sets the directory quota to the quota parameter. 

"l"b algebraically adds the quota parameter to the current directory quota. 

quota 

is the quota to be placed on the new directory. (Input) 

code 

is a standard system status code. (Output) 



Entry: mdc $set_volume quota 

This entry point is used to set the volume quota for a quota account on a logical 
volume. 

USAGE 

declare mdc_$set_vol ume_quota entry (char (*) , char (*) , bit(l) aligned, 
fixed bin, fixed bin (35)); 

call mdc_$set_vol ume_quota (volume, account, sw, quota, code); 

ARGUMENTS 

volume 

is the name of the logical volume that is to contain segments created in the new 
directory. (Input) 
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account 

is the name of the quota account in the form Person_id.Project_id.tag. The quota 
account name may contain stars. (Input) 

sw 

is a switch indicating the kind of quota change. (Input) 

"0"b sets the directory quota to the quota parameter. 

'T'b algebraically adds the quota parameter to the current directory quota. 

quota 

is the quota to be placed on the new directory. (Input) 

code 

is a standard system status code. (Output) 



Name: menu 

The menu_ subroutine provides menu display and selection services. It can display a 
menu in a window and get a selection from the user. The entries work with menu 
objects. A menu object is a pointer to an internal description of a menu. The caller 
is expected to preserve the pointer, and to perform no operation on it other than 
comparison with the null pointer or with another menu object, except through the 
menu_ subroutine. Declarations for the entries and the associated structures are in the 
include file menu_dcls.incl.pll described below in "Data Structures". 



Entry: menu $create 

This entry creates a menu object given its description. The menu data structure is 
allocated in a caller supplied area, and may be saved across processes by calling 
menu_$store. A pointer to the new menu is returned, also with the minimum size of 
a window to hold the menu. 

USAGE 

declare menu_$create entry ( (*) char (*) varying, («) char (*) varying, 
(*) char (*) varying, ptr, (*) char (1) unal, ptr, ptr, ptr, 
fixed bin (35)) ; 

call menu_$create (choices, headers, trailers, format_ptr, keys, 
area_ptr, needs_ptr, menu, code); 
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choices 

is an array of the names of the options. (Input) If the maximum number of 
choices is exceeded, the code menu_et_$too_many_options is returned. The current 
maximum is 61. 

headers 

is an array of headers. (Input) If the length of the first header is zero, then no 
headers are used. This allows the caller to specify no headers, without resorting 
to a zero-extent array, which is invalid PL/I. 

trailers 

is an array of trailers. (Input) As for headers, a zero-length first trailer means 
that no trailers are displayed. 

format_ptr 

points to a structure, menu_format, that controls formatting of the menu. (Input) 
This structure is described below in "Data Structures". 

keys 

is an array specifying the keystroke for each option. (Input) The array must have 
at least as many elements as the array of option names. If not, the error code 
menu_et_$too_few_keys is returned. It may have more keys than choices. Each 
item of the array must be unique, or menu_et_$keys_not_unique is returned. If 
the valid keys (the keys for which there are choices) are either all upper case or 
all lower case, menu_$get_choice will treat upper and lower case letters identically. 

area_ptr 

is a pointer to an area where the menu description is allocated. (Input) If the 
area is not large enough, the area condition is signalled. If this pointer is null, 
the system free area is used. 

needs_ptr 

points to the menu_requirements structure giving requirements to display the menu. 
(Input) The structure is described below in "Data Structures". The caller supplies 
this structure and fills in the version number menu_requirements_version_l, the 
remaining members are output from this entry. 

menu 

is a newly created menu object. (Output) 

code 

is a standard system error code, or an error code from menu_et_. (Output) 
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Entry: menu Sdelete 

This entry deletes a menu object from a specified value segment. 
USAGE 

declare menu_$de1ete entry (char (*) , char (*) , char (*) , fixed bin 
(35) ) ; 

call menu_$delete (dirname, entryname, menu_name, code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) It must have the value suffix. 
menu_name 

is the name that was assigned to the menu when it was stored (see the description 
of menu_$store). (Input) 

code 

is a standard system error code. (Output) 



Entry: menu Sdescribe 

This entry fills in a caller-supplied data structure describing some of the aspects of a 
menu object. The caller can use this to ensure a window is sufficiently large to hold 
a menu. 

USAGE 

declare menu_$descr i be entry (ptr, ptr, fixed bin (35)); 
call menu_$descr i be (menu, needs_ptr, code); 
ARGUMENTS 
menu 

is the menu object to describe. (Input) 
needs_ptr 

points to a structure declared like menu_requirements described in "Data 
Structures" below. (Input) The caller fills in the version to be 
menu_requirements_version_l, and the remaining members are filled in by this 
entry. 
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code 

is a standard system error code. (Output) 



Entry: menu Sdestroy 

This entry is used to delete a menu object The caller uses this to free storage of a 
menu, since the representation of a menu is not known outside the menu_ subroutine. 
This entry has no effect on screen contents or on stored menus. 

USAGE 

declare menu_$destroy entry (ptr, fixed bin (35)); 

call menu_$destroy (menu, code); 

ARGUMENTS 

menu 

is the menu object to destroy. (Input) 

code 

is a standard system error code. (Output) 



Entry: menu Sdisplay 

This entry displays a menu object on a supplied window. 
USAGE 

declare menu_$d i spl ay entry (ptr, ptr, fixed bin (35)); 

call menu_$d i spl ay (window, menu, code); 

ARGUMENTS 

window 

is a pointer to an IOCB for an I/O switch attached through window_io_. (Input) 
This window must be large enough to hold the menu. A menu window should be 
used ONLY for menu I/O, if redisplay optimizations are desired. 

menu 

is the menu object to be displayed. (Input) 

code 

is a standard system error code. (Output) 
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This entry returns a choice from a menu. The menu is assumed to be already 
displayed in the window. 

USAGE 

declare menu_$get_cho i ce entry (ptr, ptr, ptr, bit (1) aligned, 
fixed bin, fixed bin (35)); 

call menu_$get_choi ce (window, menu, f unct i on_key_i nf o, fkey, selection, 
code) ; 

ARGUMENTS 

window 

is a pointer to the IOCB for the I/O switch used to display the menu. (Input) 
menu 

is the menu object on display in the window. (Input) 
f unction_key_inf o 

is a pointer to a data structure describing the function keys available on the 
terminal. (Input) This data structure is obtained by the caller from the 
ttt_info_$function_key_data subroutine. If this pointer is null, no function keys 
are used. 

fkey 

returns a value of "l"b if a function key was hit instead of a menu selection. 
(Output) 

selection 

gives the option number or function key number chosen by the user. For an 
option, it is a number between 1 and the highest defined option, inclusive. For a 
function key, it is the number of the function key. 

code 

is a standard system error code. (Output) 
NOTES 

If a terminal has no function keys, the caller can define input escape sequences for 
function keys. These may be chosen to have mnemonic value to the end user. For 
example, if Function Key 1 is used to print a help file, the input sequence ESC h 
could replace it In some applications, this will be easier for the end user to 
remember than an unlabelled function key. The caller can define these keys by 
allocating and filling in the same function key structure normally returned by the 
ttt_info_ subroutine. 
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If a key is hit that is not one of the option keys and is not a function key, then the 
terminal bell is rung. 



Entry: menu Slist 

This entry lists the menu objects stored in a specified value segment. 
USAGE 

declare menu_$list entry (char (*) , char (*) , char (*) , ptr, fixed bin, 
ptr , f i xed bin (35) ) ; 

call menu_$list (dirname, entryname, menu_s tar name, area_ptr, 
menu_l i st_i nf o_vers i on, menu_l i st_i nf o_ptr , code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) It must have the value suffix. 
menu_starname 

is matched against the names of the menus stored in the segment. (Input) Only 
names that match menu_starname are returned, (see the description of menu_$store). 

area_ptr 

is a pointer to an area in which to allocate the structure containing the menu 
names. (Input) If it is null, the system free area is used. 

menu_list_inf o_version 

is the version of the menu_list_info structure that the caller expects. (Input) It 
must be a supported menu_list_info structure version. The only supported version 
is menu_list_info_version_l. 

menu_list_inf o_ptr 

is a pointer to the menu_list_info structure, described below under "Data 
Structures". (Output) 

code 

is a standard system error code. (Output) 
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Entry: menu Sretrieve 

This entry retrieves a menu from a specified segment. The segment must be a value 
segment. The menu data structure is allocated in a caller-supplied area. The menu 
information is copied from the menu object stored in the segment into the newly 
allocated structure. 

USAGE 

declare menu_$retr i eve entry (char (*) , char (*) , char (*) , ptr, ptr, 
fixed bin (35)) ; 

call menu_$retr i eve (dirname, entryname, menu_name, area_ptr, menu_ptr, 
code) ; 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) It must have the value suffix. 
menu_name 

is the name that was assigned to the menu when it was stored (see the description 
of menu_$store). (Input) 

area_ptr 

is a pointer to an area where the menu object is allocated. (Input) If this 
argument is null, the system free area is used. If the area is not large enough, 
the area condition is signalled. 

menu_ptr 

is a pointer to the menu object that is retrieved from the segment. (Output) 

code 

is a standard system error code. (Output) 



Entry: menu $store 

This entry stores a menu object in a specified segment. The specified segment must 
be a value segment. 
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USAGE 

declare menu_$store entry (char (*) , char (*) , char (*) , bit(l) aligned, 
ptr, fixed bin (35)) ; 

call menu_$store (dirname, entryname, menu_name, create_sw, menu_ptr, 
code) ; 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) It must have the value suffix. 
menu_name 

is a name to be assigned to the menu. (Input) 
create sw 

determines whether or not the segment is created if it does not already exist. If 
the segment does not exist, a value of "l"b will cause it to be created. (Input) 

menu_ptr 

is a pointer to the menu object that is to be stored in the segment. (Input) 

code 

is a standard system error code. (Output) 
DATA STRUCTURES 

A menu is described by the "menu_f ormat" structure. It is declared in menu_dcls.incl.pll. 

del 1 menu_format aligned based (menu_f ormat_ptr) , 

2 version fixed bin, 
2 constraints, 

3 max_width fixed bin, 

3 max_height fixed bin, 

2 n_co1umns fixed bin, 
2 flags, 

3 center_headers bit (1) unal, 

3 center_tra i 1 ers bit (1) unal, 

3 pad bi t (3^) unal , 

2 pad_char char (1) ; 
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STRUCTURE ELEMENTS 



menu_format 

specifies the format for menu display. (Input) It gives limits for number of lines 
and characters per line, specifies the number of columns (of options), and controls 
centering of headers and trailers. 

version 

must be menu_format_version_l. (Input) 
max_width 

is the width of the window the menu will be displayed on. (Input) This value is 
used for centering headers and aligning columns. 

max_height 

is the maximum height of the window, in lines. (Input) 
n_columns 

is the number of columns to use in displaying options. (Input) 
center_headers 

if set, header lines will be centered using the window width supplied above. 
(Input) If not set, they are flush with the left edge of the window. 

center_trailers 

same as center_headers, but for trailers. (Input) 

pad 

must be "0"b. (Input) 
pad_char 

is the character used for centering headers and /or trailers. (Input) 
THE MENUJ.ISTJNFO STRUCTURE 

This entry returns information in the menu_list_info structure, found in the include 
file menu_list_info.incl.pll, shown below: 

del 1 menu_l i st_i nf o aligned based (menu_J i st_i nf o_ptr) , 

2 version fixed bin, 

2 n names fixed bin, 

2 name_str i ng_ length fixed bin (21), 
2 names (menu_l i st_n_names refer 

(menu_l i st_i nfo.n_names) ) al i gned, 
3 position fixed bin (21), 

3 length fixed bin (21) , 

2 name_string character (menu_l i st_name_str i ng_l ength 

refer (menu_l i st_i nf o.name_str i ng_l ength) ) 
unal i gned; 
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STRUCTURE ELEMENTS 



version 

is the version of this structure, menu_list_info_version_l. (Output) 
n_names 

is the number of menu object names that matched the supplied starname. 
(Output) 

name_string_length 

is the total length of all the names that matched the supplied starname, 
concatenated together. (Output) 

names 

is an array of information with one entry for each name that matched the 
specified starname. (Output) 

position 

is the position in the string menu list info.name string of this menu name. 
(Output) 

length 

is the length of this menu name in the string menu_list_info.name_string. 
(Output) 

name_string 

contains all the returned names, concatenated together. (Output) The PL/ 1 
"defined" attribute can be used to advantage to refer to individual names. For 
example, we wish to print the menu name indexed by name_index. 

beg in; 

declare this_name character (menu_l i st_i nf o. 1 ength (name_i ndex) ) 
def i ned (menu_l i st_i nf o . name_str i ng) 
position (menu_l i st_i nfo.pos i t ion (name_i ndex) ) ; 

call ioa_ ("The ^d'th menu name is: ^a", name_index, this_name); 

end ; 



THE ME N U_RE QU I REMENTS STRUCTURE 

The requirements for a menu are specified by the menu_requirements structure. It is 
declared in menu_dcls.incl.pll. 

del 1 menu_requi rements aligned based (menu_requ i rements_ptr) , 
2 version fixed bin, 

2 1 i nes_needed fixed bin, 

2 width_needed fixed bin, 

2 n_options fixed bin; 
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STRUCTURE ELEMENTS 



version 

is set by the caller, and must be menu_requirements_version_l. (Input) 
lines_needed 

is the number of lines required. (Output) If the window does not have this 
number of lines, menu display will fail. 

width_needed 

is the number of columns needed. (Output) 

n_options 

is the number of options defined. (Output) 

The include file, menu_dcls.incl.pll, also provides an array of key characters that may 
be used in the menu to select options. This array can be used by the caller as input 
to the menu_$create entry. Its name is MENU_OPTION_KEYS. 



Name: metering util 

The metering_util_ subroutine contains several entry points useful for collecting 
hardcore metering data. In general, hardcore metering data elements can be categorized 
as samples, cumulative times, or cumulative counts (the latter two being cumulative 
since system initialization). Samples are snapshots of variables that describe the state 
of some system object (e.g, number of processes eligible at this instant). An example 
of a cumulative count is the total number of read I/Os issued to a particular disk 
device since system initialization, while an example of a cumulative time is the total 
busy time of a particular disk device while processing read I/Os. It is easy to 
compute average I/O time for a read to a particular device from these last two items. 
If a given set of metering data is sampled periodically, then more interesting, 
time-varying data can be computed. For example, the average I/O time for a read 
during a certain time interval can be computed. That interval is the time between any 
two samples of the data; subtracting the earlier cumulative count of I/Os from the 
later count yields the incremental count (i.e., the count of I/Os during the interval). 

Multics metering commands are designed for interactive use, with the interval 
boundaries defined by the user in real time. Typically, metering commands support the 
following control arguments: 

-report 

prints a report of activity since the last interval boundary (or since system 
initialization, if no boundary has been defined). 
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-reset 

defines an interval boundary for this metering program; all further invocations of 
this command display data reflecting activity since this boundary. 

-report_reset 

reports and then resets. 

Under this scheme, each display of data, establishment of an interval boundary, etc., is 
done in a separate invocation of the same metering program. This allows the user to 
establish an interval boundary, exercise the system in some fashion, and then print 
data describing the system performance while it was being exercised. Additionally, a 
user can run any number of metering programs, each with independent interval 
boundaries. These considerations imply that metering data collection (which is sampling 
of hardcore data bases) should be global to the process (in order to exist through 
multiple invocations of the same metering command) and be distinguished among 
different metering programs. 

The metering_util_ subroutine satisfies the above requirements in the following manner. 
On the first invocation of a metering program, the program calls 
metering_util_$define_region to define the hardcore data of interest: the collection of 
such data can be an arbitrary number of contiguous regions in an arbitrary number of 
hardcore data bases. On this first invocation, metering_util_ allocates sufficient static 
storage to maintain two copies of each hardcore region. This storage is allocated in a 
system free area in the process directory. A unique identifier in the form of a 
nonzero integer is assigned and returned to the invoker. This unique identifier is used 
in all further communications with metering_util_ by that metering program to identify 
the set of hardcore regions defined in this first call. Current buffers are filled by 
calls to metering_util_$fill_buffers, at which time the hardcore regions specified in the 
call to metering_util_$define_region are copied into the corresponding current buffers. 
Previous buffers are initially set to binary zeros. On calls to metering_util_$reset, the 
current buffers are copied into the previous buffers. On calls to metering_util_$fill_buffers, 
pointers to the current and previous buffers for each hardcore region are returned. 

To use this subroutine, sufficient access to copy all hardcore regions specified is 
required. Access to the phcs_ gate is sufficient. If all hardcore regions specified are 
defined in >sll>ring_zero_meters_limits.ascii, then access to metering_gate_ is sufficient. 



Entry: metering_util_$define_regions 

This entry is used to define a set of sections of hardcore data bases which are of 
interest to the invoker. Upon return, sufficient static storage has been allocated to 
contain two copies of each hardcore region specified in the call; this storage has also 
been initialized to zero. 
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USAGE 

declare code fixed bin (35) 5 declare unique_index fixed bin; declare 
meter i ng_ut i l_$def i ne_reg i ons entry options (variable); 

call meter i ng_uti l_$def i ne_regions (uni que_i ndex, code, 

hardcore_seg_l , beg i n_reg i on__l , end_reg i on_l , , 

... hardcore_seg_n, beg i n_reg ion_n, end_region_n) ; 

ARGUMENTS 
unique_index 

is a unique identifier for the set of regions. This identifier must be used in calls 
to other metering_util_ entry points. (Output) 

code 

is a standard status code. The code error_table_$wrong_no_of_args is returned if 
the number of arguments remaining is not modulo 3. (Output) 

The remaining arguments must be in groups of three, as shown in the calling sequence 
above. Each such group defines a hardcore region by specifying a hardcore segment 
and a contiguous region within the segment. The arguments in each group, in order, 
are the following: 

hardcore_seg_i 

identifies the ring 0 data base. It may be of the form char (*), in which case it 
is assumed to be the name of a ring 0 segment; or of the form ptr aligned, in 
which case it is assumed to be a pointer to the segment In the latter case, only 
the segment number is significant. (Input) 

begin_region_i 

identifies the beginning of the region in the ring 0 data base. It may be of the 
form char (*), in which case it is assumed to be the name of an external symbol 
in hardcore_seg_i; or of the form fixed bin, in which case it is assumed to be a 
word offset into hardcore_seg_i. (Input) 

end_region_i 

identifies the end of the region in the ring 0 data base. It may be of the form 
char (*), in which case it is assumed to be the name of an external symbol in 
hardcore_seg_i that refers to the next word beyond the end of the region; or of 
the form fixed bin, in which case it is assumed to be the length of the region in 
words. (Input) 

NOTES 

Any errors encountered by this entry point are reported to the user by means of the 
sub_err_ subroutine. Examples of such errors are invalid segment names or symbol 
names, or invalid region specification (e.g., nonpositive length). Errors of this sort are 
always programming errors, and are not external circumstances from which the calling 
program can be expected to recover. 
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Entry: metering__util_J&f ill_buf f ers 

This entry is used to copy the current contents of all regions defined for the 

specified unique identifier into the current buffers for that unique identifier, and to 

return pointers to the current and previous buffers for these regions. 

USAGE 

declare meter i ng_ut i l_$f i 1 l_buf f ers entry (fixed bin, fixed b i n (7 1 ) • 
char(10), (*) ptr, (*) ptr, f i xed b i n (35) ) 5 

call meter i ng_uti l_$fi 1 l_buffers (unique_i ndex, meter_time, 
f ormatted_t ime, current_ptrs , previous_ptrs, code) ; 

ARGUMENTS 

unique_index 

is the unique identifier returned by metering_util_$define_regions (above). (Input) 
meter_tirne 

is the total metering time in microseconds. The total metering time is defined as 
the time between the last call to metering_util_$reset and this call. If 
metering_util_$reset has not been called, the total metering time is defined as the 
time between the last system bootload and this call. (Output) 

formatted_time 

is the total metering time in a format suitable for printing. This format is 
HHHH:«M:SS 

where this represents the decomposition of total metering time into hours (HH), 
minutes (MM), and seconds (SS). (Output) 

current_ptrs 

is an array of pointers that, on return, contain pointers to the current buffers for 
the hardcore regions defined in the call to metering_util_$define_regions. The 
number of elements in this array must be equal to the number of hardcore 
regions defined in the call to metering_util$define regions. The elements of this 
array are pointers to the current buffers for the corresponding hardcore regions. 
Specifically, current_ptrs (i) contains on return a pointer to the current buffer for 
hardcore_seg_i (defined above). (Output) 

previous_ptrs 

is an array of pointers which, on return, contain pointers to the previous buffers 
for the hardcore regions defined in the call to metering_util_$define_regions. The 
number of elements in this array must be equal to the number of hardcore 
regions defined in the call to metering_util_$define regions. The elements of this 
array are pointers to the previous buffers for the corresponding hardcore regions. 
Specifically, previous_ptrs (i) contains on return a pointer to the previous buffer 
for hardcore_seg_i (defined above). (Output) 
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code 

is a standard status code. If either the array current_ptrs or the array 
previous_ptrs does not have the proper number of elements (see above), the code 
error_table_$invalid_array_size is returned, and no action is performed. (Output) 



Entry: metering_util Sreset 

This entry point is called to reset the metering interval to the time of this call. This 
is done by copying the current buffers into the previous buffers for all regions 
defined for the unique index specified. 

USAGE 

declare meter i ng_ut i l = $reset entry (fixed bin, fixed bin (35)); 

call meter ing_uti l_$reset (un i que_i ndex, code); 

ARGUMENTS 

unique_index 

is as above. (Input) 

code 

is as above. (Output) 



Name: meter gate 

The meter_gate_ subroutine is an entry point (used by the meter_gate metering 
command) that returns data about specific gate entries to the caller. 

USAGE 

declare meter_gate_ entry (char (*) , ptr fixed bin (35)); 
call meter_gate_ (gate_name, array_ptr, code); 
ARGUMENTS 
gate_name 

is the name of the gate whose entries are to be metered. (Input) 
array_ptr 

is a pointer to an array described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 
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STRUCTURE 

The second argument to meter_gate_ is a pointer to an array of entry names to be 
metered. This array has the following format: 

del 1 arg_array aligned based (array_ptr) , 

2 num_ents fixed bin, 

2 info (0 refer (arg_array .num_ents) ) , 

3 name char (32) , 

3 cal 1 s f i xed bin, 

3 page_waits fixed bin, 

3 time fixed bin (71) ; 

STRUCTURE ELEMENTS 

num_ents 

is the number of entries in the array info. 

name 

is the entryname. 

calls 

is the number of calls to that entry. 
page_waits 

is the number of page waits by that entry. 

time 

is the CPU time in (microseconds) used by that entry. 



Name: mhes 

Entry: mhcs_$get_seg_usage 

This entry point returns the number of page faults taken on a segment since its 
creation. 

USAGE 

declare mhcs_$get_seg_usage entry (char (*) , char (*) , fixed bin (35) » 
fixed bin (35)) ; 

call mhcs_$get_seg_usage (dir_name, entryname, use, code); 
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ARGUMENTS 
dir_name 

is the directory containing the segment. (Input) 
entryname 

is the entry name of the segment. (Input) 

use 

is the page fault count. (Output) 

code 

is a standard status code. (Output) 
NOTES 

This entry point works for segments only and cannot be used to determine the page 
faults on a directory. 



Entry: mhcs $get seg usage ptr 

This entry point works the same as mhcs_$get_seg_usage except that it takes a pointer 
to the segment 



fixed bin (35)) ;~ 
call mhcs_$get_seg_usage_ptr (s_ptr, use, code); 
ARGUMENTS 
s_ptr 

is a pointer to the segment. (Input) 

use 

is the page fault count. (Output) 

code 

is a standard status code. (Output) 



USAGE 



declare mhc 




(35), 



2-605 



AG93-05 



mlr_ 

Name: mlr 

The mlr_ subroutine moves a character string by copying the characters from left to 
right. 

USAGE 

declare mlr_ entry (ptr, fixed bin(21), ptr, fixed bi n (21) ) ; 
call mlr_ (input_ptr, input_lth, output_ptr, output_lth); 
ARGUMENTS 
input_ptr 

is a pointer to the input string. (Input) 
input_lth 

is the length of the input string in characters. (Input) 
output ptr 

is a pointer to the output string. (Input) 
output_lth 

is the length of the output string in characters. (Input) 
NOTES 

If the output string is shorter than the input string, only the first output_lth 
characters of the input string are moved. If the output string is longer than the input 
string, the output string is padded on the right with blanks. 



The following call to mlr_ — 



call mlr_ (addcharno (addr (text), start), 1th, 

addcharno (addr (text), start-N) , 1th); 



where N is a positive number is equivalent to the PL/ 1 statement — 

substr (text, start, 1th) = substr (text, start+N, 1th); 
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Name: mode string 

The mode_string_ subroutine provides a set of entry points for handling mode strings. 
Mode strings are a way for a user to pass control information to a command or 
subsystem. A mode string is a character string which contains one or more modes, or 
is empty. A mode is a character string, separated from other modes by a comma. A 
mode specifies the name of a parameter and (implicitly) the data type and value of 
the parameter. Parameter names are character strings of one to 32 characters. 
Parameters may be one of the following types: Boolean, Numeric, or Character. The 
type and value of the parameter are determined in the following way: 

If the first character in the mode is the circumflex character (" A "), then the 
parameter is a Boolean type whose value is "false" and whose name is all the 
remaining characters in the mode. 

If the mode contains the equal character ("="), then the name of the parameter is 
given by all the characters before the equal character. If all characters after the 
equal character are decimal digits or sign characters ("+" or "-"), then the 
parameter is of type Numeric, and the value is the number given, which is of 
precision fixed binary (35,0). Otherwise, the type is Character, and the value is 
the character string beginning after the first equal character. The value may be 
the null string. The character string may be enclosed in quotes to distinguish it 
from a Numeric value, or if it contains a reserved character. Reserved characters 
are circumflex C) , comma, period, equals (=), double quote, and any character 
other than the 94 printing graphic characters in the Multics character set. 
Character values are limited to 32 characters in length. 

If the mode does not contain the equal character, then if the last N characters 
are decimal digits or sign characters (where N > 1), then the parameter is of type 
Numeric, and those digits specify the value. Otherwise, the parameter is of type 
Boolean and the value is "true". 

White space is permitted anywhere in a mode string. White space, however, is not 
insignificant; it separates tokens and may cause syntax errors if delimiter 
characters, such as comma and equal, are omitted. White space is defined as any 
number of the characters SPACE, TAB, NEWLINE, FORMFEED or VERTICAL 
TAB in any order. This definition is the same as the one used by the Multics 
command processor when scanning active function return values produced by the 
" | C" construct. 

A period (.) is permitted at the end of the mode string to delimit it. If any 
non white characters follow an unquoted period in the mode string, the mode 
string is in incorrect format. 

Ambiguous modes are not permitted. An ambiguous mode is one which begins 
with one or more circumflexes (~) and which contains a Numeric or Character 
value. 
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EXAMPLES 



mode 


name 


type 


value 


crecho 


crecho 


Bool ean 


true 


-lfecho 


1 f echo 


Bool ean 


f al se 


—tab 


tab 


Bool ean 


true 


H79 


1 1 


Numer i c 


79 


11=79 


1 1 


Numer i c 


79 


i ndent=~5 


i ndent 


Numer i c 


-5 


aud i t_tr i gger=@ 


aud i t_tr i gger Character 


@ 


more_mode=scrol 1 


more_mode 


Character 


scrol 1 


prompt=" -> " 


prompt 


Character 


• I _> ii 


prompt= 


prompt 


Character 


llll 


illegal specifications 






-1179 —1179 


-11=79 


-1 l=foo -11 


="foo" 


x=y=2 


x y 


"foo" 11" 


foo" 



INFO STRUCTURE 



The mode_string_ entries describe a mode string with the following data structures, 
declared in mode_string_info. incl.pl 1 



del 1 mode_str i ng_i nf o 
2 version 
2 number 
2 modes 



aligned based (mode_str i ng_i nf o_ptr) , 
fixed bin, 
f i xed bin, 

(number_of_modes refer 
(mode_str i ng_i nf o. number) ) 
1 i ke mode val ue; 



STRUCTURE ELEMENTS 
version 

gives the version of the structure. The most recent version is given by the 
constant mode_string_info_version_2, also declared in the include file. If the 
caller is supplying the structure as input, the caller must ensure that this value is 
set. If the structure is returned by one of the entries, the value will be set, and 
the caller should check it. 



number 

gives the number of parameters in the mode string. 



lodes 



are the component modes of the mode string. 
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A parameter (mode value) is described by the following structure: 



del 1 mode value 



2 mode name 



2 version 



aligned based (mode_va 1 ue_ptr) , 
f i xed bin, 
char (32) una! , 



2 flags, 

3 bool ean_va 1 uep 
3 numer i c_val uep 
3 char_valuep 
3 boolean_value 
3 padl 



bit (1) unal, 

bit (1) unal, 

bit (1) unal , 

bit (1) unal , 

bit (32) unal, 



2 numer i c_val ue 

2 char_value 

2 code 

2 pad2 



f i xed b i n (35) > 
char (32) varying, 
fixed bin (35) , 
bit (36) ; 



STRUCTURE ELEMENTS 
version 

gives the version of the structure. The most recent version is given by the 
constant mode_value_version_3, also declared in the include file. 

mode_name 

is the name of the parameter 

flags 

describe the parameter. 

boolean_valuep 

is "l"b for a Boolean parameter. 

numeric_valuep 

is "l"b for a Numeric parameter. 

char = valuep 

is T'b for a Character parameter. 

boolean_value 

is valid only for a Boolean parameter, and holds its value. 

padl 

must be "0"b. 
numeric_value 

is valid only for a Numeric parameter, and holds its value. 
char_value 

is valid only for a Character parameter, and holds its value. Note that the string 
is varying to permit (quoted) trailing whitespace in a mode value. 
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code 

is an error code for the particular mode, and normally is zero. 

pad2 

must be "0"b. 

For all entry points in the mode_string_ subroutine, the following codes can be 
returned: 

error_table_$bad_mode_syntax 

for a mode string with bad syntax. 
error_table_$undef ined_mode 

when a mode searched for is not found. 
error_table_$mode_string_truncated 

when mode string to be returned to the caller will not fit in the caller-supplied 

string. In this case, the string returned is truncated to the nearest whole mode. 



Entry: mode string Scombine 

The mode_string_$combine entry point returns a mode string which represents the 
union of the modes defined in the two input arguments. The order of modes in the 
output string is not defined. If the same parameter is given in both structures, the 
type and value are taken from the second structure. 

USAGE 

declare mode_str i ng_$comb i ne entry (ptr, ptr, char (*) , fixed bin (35)) 5 

call mode_str i ng_$comb i ne (mode_str i ng_i nf o_ptr 1 , mode_str i ng_i nf o_ptr 2 , 
modestr , code) ; 

ARGUMENTS 

mode_string_inf o_ptrl 

points to the first mode_string_info structure. (Input) 

mode_string_inf o_ptr2 

points to the second mode_string_info structure. (Input) This pointer may be null, 
and the string is formed from the first structure only. 

modestr 

is a mode string. (Output) 

code 

is a standard system error code. (Output) 
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Entry: mode string Sdelete 

The mode_string_$delete entry point returns a new mode string, with any mention of 
specified modes deleted. It is not an error if any of the specified modes are absent 
from the structure. 

USAGE 

declare mode_str i ng_$del ete entry (ptr, («) char (*) , char (*) , 
fixed bin (35)) ; 

call mode_str i ng_$de 1 ete (models tr i ng_i nfo_ptr , excludes, modes tr, 
code) ; 

ARGUMENTS 

mode_string_inf o_ptr 

is a pointer to the mode_string_info structure. (Input) 

excludes 

is the array of names to be excluded. (Input) To exclude a single name, a scalar 
may be given. (Input) 

modestr 

is a mode string. (Output) 

code 

is a standard system error code. (Output) 



Entry: mode string Sget 

The mode_string_$get entry point returns a mode string formed from the mode string 
info structure supplied it. If the caller supplied string is not long enough to hold the 
mode string, it is truncated at the nearest whole mode, and the error code 
error_table_$mode_string_truncated is returned. This ensures that the mode string 
returned is valid. 

USAGE 

declare mode_str i ng_$get entry (ptr, char (*) , fixed bin (35)); 
call models tr i ng_$get (mode_str i ng_i nf o_ptr , modestr, code); 
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ARGUMENTS 

mode_string_inf o_ptr 

is a pointer to the mode_string_info structure. (Input) 

modestr 

is a mode string. (Output) 

code 

is a standard system error code. (Output) 



Entry: mode string $get error 

The mode_string_$get_error entry point is just like the mode_string_$get entry point 
except that the string returned only contains modes where mode_value.code was 
nonzero. This selection mechanism can be used to return a list of bad modes when a 
call to iox_$modes fails, for inclusion in an error message. 

declare mode_str i ng_$get_error entry (ptr, char (*) , fixed bin (35)); 

call mode_str i ng_$get_er ror (mode_str i ng_i nf o_ptr , modestr, code); 

ARGUMENTS 

mode_string_inf o_ptr 

is a pointer to the mode_string_info structure. (Input) 

modestr 

is a mode string. (Output) 

code 

is a standard system error code. (Output) 



Entry: mode string $get mode 

The mode_string_$get_mode entry point parses a supplied mode string and extracts a 
single parameter from it, 'filling in a caller-supplied mode_value structure (remember 
to set the version), or returning an error code if the parameter is not present in the 
string. 

USAGE 

declare mode_str i ng_$get_mode (char (*) , char (*) . ptr, fixed b i n (35) ) * 
call mode_str i ng_$get_mode (modestr, mode_name ; mode_va 1 ue_ptr ; code); 
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ARGUMENTS 

modestr 

is a mode string. (Output) 

mode_name 

is the name of the mode to search for. (Input) 

mode_value_ptr 

is a pointer to a mode_value structure. (Input) 

code 

is a standard system error code. (Output) 



Entry: mode string Sparse 

The mode_string_$parse entry point parses a mode string, allocating a structure giving 
the parameters specified in the string. 

USAGE 

declare mode_str i ng_$parse entry (char (*) , ptr, ptr, fixed bin (35)) J 

call mode_str i ng_$parse (modestr, areap, mode_str i ng_i nf o_ptr , code); 

ARGUMENTS 

modestr 

is a mode string. (Input) 

areap 

points to an area where the mode string info structure may be allocated. (Input) 
If a null pointer is provided, the system area is used. 

mode_string_inf o_ptr 

is a pointer to a mode_string_info structure. (Output) 

code 

is a standard system error code. (Output) 
NOTES 

The error code error_table_$bad_mode_value has been provided for the use of callers 
of this interface to return when rejecting modes for incorrect type. 
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Name: mrl 

The mrl_ subroutine moves a character string by copying the characters from right to 
left. 

USAGE 

declare mrl_ entry (ptr, fixed b i n (2 1 ) , ptr, fixed b i n (2 1) ) ; 
call mrl_ (input_ptr, input_lth, output_ptr, output_l th) ; 
ARGUMENTS 
input_ptr 

is a pointer to the input string. (Input) 
input_lth 

is the length of the input string in characters. (Input) 
output_ptr 

is a pointer to the output string. (Input) 
outputjth 

is the length of the output string in characters. (Input) 
NOTES 

If the output string is shorter than the input string, only the last output_lth characters 
of the input string are moved. If the output string is longer than the input string, 
the output string is padded on the left with blanks. 



The following PL/I statement — 

substr (text, start, 1th) = substr (text, start+N, 1th); 

where N is a positive number will not execute properly as the code generated by the 
compiler moves the character string from left to right which destroys the contents of 
the string. Instead, the following call to mrl_ should be used — 



call mr1_ (addcharno (addr (text), start), 1th, 

addcharno (addr (text), start+N), 1th); 
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Name: msf manager 

The msf_manager_ subroutine provides a centralized and consistent facility for handling 
multisegment files. Multisegment files are files that can require more than one 
segment for storage. Examples of multisegment files are listings, data used through 
I/O switches, and APL workspaces. The msf_manager_ subroutine makes multisegment 
files almost as easy to use as single segment files in many applications. 

A multisegment file is composed of one or more components, each the size of a 
segment, identified by consecutive unsigned integers. Any word in a single segment file 
can be specified by a pathname and a word offset. Any word in a multisegment file 
can be specified by a pathname, component number, and word offset within the 
component. The msf_manager_ subroutine provides the means for creating, accessing, 
and deleting components, truncating the multisegment file, and controlling access. 

In this implementation, a multisegment file with only component 0 is stored as a 
single segment file, unless the msf_manager_$msf_get_ptr entrypoint was responsible 
for creating the file, in which case it is stored as a multisegment file with only one 
component. If components other than 0 are present, they are stored as segments with 
names corresponding to the ASCII representation of their component numbers in a 
directory with the pathname of the multisegment file. 



The ACL of a multisegment file is maintained on each of its components. This ACL 
is translated into a similar directory ACL maintained on the directory portion of the 
multisegment file. The directory ACL is maintained such that all users have at least 
"s" access to the directory portion so that all users can determine their actual access 
mode to the multisegment file. 



To keep information between calls, the msf_manager_ subroutine stores information 
about files in per-process data structures called file control blocks. The user is 
returned a pointer to a file control block by the entry point msf_manager_$open. 
This pointer, fcb_ptr, is the caller's means of identifying the multisegment file to the 
other msf_manager_ entry points. The file control block is freed by the msf_manager_$close 
entry point 



Entry: msf manager $acl add 

This entry point adds the specified access modes to the ACL of a multisegment file. 
USAGE 

declare msf_manager_$ac l_add entry (ptr, ptr, fixed bin, fixed bin (35)); 
call msf_manager_$acl_add (fcb_ptr, acl_ptr, acl_count, code); 



2-615 



AG93-05 



msf_manager 



msf_manager_ 



ARGUMENTS 



fcb_ptr 

is a pointer to the file control block. (Input) 
acl_ptr 

points to the user-supplied segment_acl_array structure (described under "Notes" 
below). (Input) 

acl_count 

is the number of ACL entries in the segment_acl_array structure. (Input) 

code 

is a storage system status code. (Output) It can be: 
error_table_$argerr 

the erroneous ACL entries in the segment_acl_array structure have status_code 
set to an appropriate error code. No processing is performed. 



NOTES 



The following is the segment_acl_array structure (declared in acl_structures.incl.pll): 

del 1 segment_acl_array (acl_count) aligned based (acl_ptr) , 

2 access_name char (32) , 

2 modes b i t (36) , 

2 zero_pad bit (36) , 

2 status code fixed bin (35); 



STRUCTURE ELEMENTS 



access_name 

is the access name (in the form Person_id.Project_id.tag) 
process to which this ACL entry applies. 



that identifies the 



modes 

contains the modes for this access name. The first three bits correspond to the 
modes read, execute, and write. The remaining bits must be O's. For example, rw 
access is expressed as "lOT'b. The include file access_mode_values.incl.pll defines 
mnemonics for these values: 



del 



(N_ACCESS 
R_ACCESS 
E_ACCESS 
W_ACCESS 
RE_ACCESS 
REW_AGCESS 
RW ACCESS 



nit 
nit 
nit 
nit 
nit 
n i t 
nit 



"000"b) , 
"100"b) , 
M 010"b) , 
"001"b) , 
"110"b) , 
("1 1 l"b) , 
("101"b)) , 



bit (3) internal static options (constant); 
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zero_pad 

must contain the value zero. (This field is for use with extended access and may 
only be used by the system.) 

status_code 

is a storage system status code for this ACL entry only. 



Entry: msf__manager_$acl_delete 

This entry point deletes ACL entries from the ACL of a multisegment file. 
USAGE 

declare msf_manager_$acl_del ete entry (ptr, ptr, fixed bin, 
fixed bin (35)) ; 

call msf_manager_$ac l_del ete (fcb_ptr, acl_ptr, acl_count, code); 

ARGUMENTS 

fcb_ptr 

is a pointer to the file control block. (Input) 
acl_ptr 

points to a user-supplied delete_acl structure. See "Notes" below. (Input) 
acl_count 

is the number of ACL entries in the delete_acl structure. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

The delete_acl structure (declared in acl_structures.incl.pll) is as follows: 

del 1 delete_acl (acl_count) aligned based (acl_ptr), 
2 access_name char (32) , 

2 status_code fixed bin(35); 

STRUCTURE ELEMENTS 

access_name 

is the access name (in the form Person_id. Projected. tag) of an ACL entry to be 
deleted. 

status_code 

is a storage system status code for this ACL entry only. 
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NOTES 

If code is error_table_$argerr, no processing is performed and status_code in each 
erroneous ACL entry is set to an appropriate error code. 

If an access name matches no name already on the ACL, then the status_code for 
that delete_acl entry is set to error_tafcle_$user_not_found. Processing continues to the 
end of the delete_acl structure and code is returned as 0. 



Entry: msf manager $acl__list 

This entry point returns the access control list (ACL) of a multisegment file. 
USAGE 

declare msf_manager_$ac 1_1 i st entry (ptr, ptr, ptr, ptr, fixed bin, 
f i xed bin (35) ) ; 

call msf_manager_$acl_l i st (fcb_ptr, area_ptr, area_ret_ptr , acl_ptr, 
ac l_count , code) ; 

ARGUMENTS 

fcb_ptr 

is a pointer to the file control block. (Input) 
area_ptr 

points to an area in which the list of ACL entries, which make up the entire 
ACL of the multisegment file, is allocated. If area_ptr is null, then the user 
wants access modes for certain ACL entries; these will be specified by the 
structure pointed to by acl_ptr. (Input) 

area_ret_ptr 

points to the start of the allocated list of ACL entries. (Output) 
acl_ptr 

if area_ptr is null, then acl_ptr points to an ACL structure, segment_acl_array, 
(described in the msf_manager_$acl_add entry point above) into which mode 
information is placed for the access names specified in that same structure. 
(Input) 

acl_count 

is the number of entries in the segment_acl_array structure. (Input/ Output) 
Input 

is the number of entries in the ACL structure identified by ael_ptr. 
Output 

is the number of entries in the segment_acl_array structure allocated in the 
area pointed to by area_ptr, if area_ptr is not null. 
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code 

is a storage system status code. (Output) 
NOTES 

If acl_ptr is used to obtain modes for specified access names (rather than obtaining 

modes for all access names in area_ret_ptr), then each ACL entry in the 

segment_acl_array structure either has status_code set to 0 and contains the 

multisegment mode of the file or has status_code set to error_table_$user_not_found 
and contains a mode of 0. 



Entry: msf manager $acl replace 

This entry point replaces the ACL of a multisegment file. 
USAGE 

declare msf_manager_$ac l_repl ace entry (ptr, ptr, fixed bin, bit(l), 
f i xed bin (35) ) » 

call msf_manager__$acl__repl ace (fcb_ptr, acl__ptr, acl_count, 
no_sysdaemon__sw code) ; 

ARGUMENTS 

fcb_ptr 

is a pointer to the file control block. (Input) 
acl_ptr 

points to the user-supplied segment_acl_array structure (described in the 
msf__manager_$acl_add entry point above) that is to replace the current ACL. 
(Input) 

acl_count 

is the number of entries in the segment_acl_array structure. (Input) 
no_sysdaemon_sw 

is a switch that indicates whether an rw *.SysDaemon.* entry is to be put on the 
ACL of the multisegment file after the existing ACL has been deleted and before 
the user-supplied segment_acl_array entries are added. (Input) 
"0"b adds rw *.SysDaemon.* entry. 

'T'b replaces the existing ACL with only the user-supplied segment_aci_array. 

code 

is a storage system status code. (Output) 
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NOTES 

If acl_count is zero, the existing ACL is deleted and only the action indicated (if any) 
by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, 
processing of the segment_acl_array entries is performed top to bottom, allowing a 
later entry to overwrite a previous one if the access_name in the segment_acl_array 
structure is identical. 



Entry: msf manager $adjust 



The msf_manager_$adjust entry point optionally sets the bit count, truncates, and 

terminates the components of a multisegment file. The number of the last component 
| and its bit count must be given. The bit counts of all components but the last are set 
| to the first component's max_length*36. All components with numbers greater than the 

given component are deleted. All components that have been initiated are terminated. 

A 3-bit switch is used to control these actions. 



USAGE 



_I 1 _ _ _ r , £ » *4 : ■ . f. 4- /nf r- 

UCCldi c ins i maiiayci yaujusi ciui j \y \.i 



bit (3) , fixed bin (35)) 



call msf _manager_$adjust (fcb_ptr, component, be, switch, code); 

ARGUMENTS 

fcb_ptr 

is a pointer to the file control block. (Input) 
component 

is the number of the last component. (Input) 



is the bit count to be placed on the last component. (Input) 
switch 

is a 3-bit count/ truncate/ terminate switch. (Input) 

bit count 

"0"b do not set the bit count. 

"l"b set the bit count, 
truncate 

"0"b do not truncate the given component. 

"l"b truncate the given component to the length specified in the be 
argument, 
terminate 

"0"b do not terminate the component. 
"l"b terminate the component. 
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code 

is a storage system status code. (Output) 



Entry: msf manager Sciose 

This entry point terminates all components that the file control block indicates are 
initiated and frees the file control block. 

USAGE 

declare msf_manager_$c 1 ose entry (ptr) ; 
call msf _manager_$c lose (f cb_ptr) ; 
ARGUMENTS 
fcb_ptr 

is the pointer to the file control block. 



Entry: msf manager Sget ptr 

This entry point returns a pointer to a specified component in a multisegment file. 
The component can be created if it does not exist. If the file is a single segment 
file, and a component greater than 0 is requested, the single segment is converted to a 
component 0. (See also the msf_manager_$msf _get_ptr entry point.) 

USAGE 

declare msf_manager_$get_ptr entry (ptr, fixed bin, bit(l), ptr, 
fixed bin (24), fixed bin (35)); 

call msf_manager_$get_ptr (fcb_ptr, component, create_sw, seg_ptr, be, 
code) ; 

ARGUMENTS 

fcb_ptr 

is a pointer to the file control block. (Input) 
component 

is the number of the component desired. (Input) 

create_sw 

is the create switch. (Input) 

"l"b create the component if it does not exist 

"0"b do not create the component if it does not exist. 
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seg_ptr 

is a pointer to the specified component in the file, or null (if there is an error). 
(Output) 

be 

is the bit count of the component. (Output) 

code 

is a storage system status code. (Output) It can be: 
error_table_$noentry 

if the component requested did not exist and create_sw is off. 



Entry: msf manager__$msf get ptr 

This entry point returns a pointer to a specified component in a multisegment file. 
The component can be created if it does not exist. If the file is a single segment 
file, and the requested component is not component 0, the single segment is converted 
to a multisegment file. This change does not affect a previously returned pointer to 
component 0. If the file does not exist, it is created as a "multi-segment file" with a 
single component. This entry point never creates a single segment file. (See also the 
msf_manager_$get_ptr entrypoint.) 

USAGE 

declare msf_manager_$msf_get_ptr entry (ptr, fixed bin, bit(l), ptr, 
fixed bin (24) , fixed bin (35)); 

call msf_manager_$msf_get_ptr (fcb_ptr, component, create_sw, seg_ptr, 
be, code) ; 

ARGUMENTS 

fcb_ptr 

is a pointer to the file control block. (Input) 
component 

is the number of the component desired. (Input) 

create_sw 

is the create switch. (Input) 

"l"b create the component if it does not exist. 

"0"b do not create the component if it does not exist. 

seg_ptr 

is a pointer to the specified component in the file, or null (if there is an error). 
(Output) 
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be 

is the bit count of the component (Output) 

code 

is a storage system status code. (Output) It can be: 
error_table_$noentry 

if the component requested did not exist and create_sw is off. 



Entry: msf manager Sopen 

The msf_manager_$open entry point creates a file control block and returns a pointer 
to it. The file need not exist for a file control block to be created for it. 

USAGE 

declare msf_manager_$open entry (char.(*) , char (*) , ptr, fixed bin (35)); 
call msf_manager_$open (dir_name, entryname, fcb_ptr, code); 
ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the multisegment file. (Input) 
fcb_ptr 

is a pointer to the file control block. (Output) 

code 

is a storage system status code. The code error_table_$dirseg is returned when an 
attempt is made to open a directory. (Output) 

NOTES 

If the file does not exist, fcb_ptr is nonnull and the code error_table_$noentry is 

returned. If the file cannot be opened, fcb_ptr is null and the value of code returned 
indicates the reason for failure. 
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Name: mvt 

The mvt_ subroutine provides for extremely efficient translation of character strings 
using translations which are not known at compile time. 

USAGE 

declare mvt_ entry (ptr, ptr, fixed bi n (21) , char (512) aligned); 

call mvt_ (i nput_str i ng_ptr , output_str i ng_ptr , string_lth, 
trans 1 ate_tabl e) ; 

ARGUMENTS 

input_string_ptr 

is a pointer to the unaligned string to be translated. (Input) 

output_string_ptr 

is a pointer to the string where the results of the translation will be placed. 
(Input) 

string^lth 

is the length of both the input string and the output string in characters. (Input) 
translate_table 

is the translation table which defines the actual translation. See 
mvt_$make_translation_table for a description of how to create this table. (Input) 



Entry: mvt Smake translation table 

This entry point creates the translation table used by the mvt_ subroutine given the 

second and third arguments which would be supplied to the PL/ 1 translate builtin 
function. 

USAGE 

declare mvt_$make_trans 1 at ion_table entry (char (*) , char (*) , char (512) 
al i gned) ; 

call mvt_$make_translation_table (trans 1 ated__l i st , untrans 1 ated__l i st , 
trans 1 ate_table) ; 

ARGUMENTS 

translated_list 

is the second argument to the PL/I translate builtin and specifies the result of 
translating any occurrence of the corresponding characters in untranslated_list 
present in the input string of the mvt_ entry described above. (Input) 
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untransiated_iist 

is the third argument to the PL/I translate builtin and specifies the list of 
characters which will be translated if found in the input string. (Input) 

translate_table 

is set to the translate table which defines the desired translation. (Output) 
NOTES 

The table constructed by this subroutine will cause any occurence of the N'th 
character in untranslated_list present in the input string of mvt_ to be converted into 
the N'th character in translated_list. See the description of the PL/I translate builtin 
for more information. 

If the PL/ 1 builtin would have been used with only two arguments, use the value of 
the collate9 builtin for the untranslated_list argument. 



Name: nd handler 

The nd_handler_ subroutine attempts to resolve the name duplication caused when a 
program tries to create a segment, multisegment file, or link in a directory that 
already contains an entry by the same name. If the existing entry has additional 
names, nd_handler_ tries to delete the name needed for the new entry and, if 
successful, prints a warning message. If the existing entry has only one name 5 
nd_handler_ queries the user whether or not to delete it. A zero status code in either 
case means that nd_handler_ has succeeded, and the calling program can retry creating 
the new entry. 

USAGE 

del nd_handler_ entry (char (*) , char (*) , char (*) , fixed bin (35)); 

call nd_handler_ (caller, dn, en, code); 

ARGUMENTS 

caller 

is the name of the calling program, used in printed messages. (Input) 

dn 

is the pathname of the directory involved. (Input) 

en 

is the name of the entry that the calling program wants to create. (Input) 
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code 

is a standard status code. (Output) It can be: 
0 

if the old entryname has been removed. 
error_table_$action_not_perf ormed 

if the user answered "no" to a query, 
other codes 

if the old entryname could not be removed for some other reason such as 
lack of access. An error message is then printed by nd_handler_. 

NOTES 

This subroutine is usually called after another subroutine call has returned 
error_table_$namedup. If nd_handler_ returns a zero status code, the other subroutine 
is called a second time. A warning message of the following kind is printed if the 
existing entry has multiple names: 

caller: Name duplication. Old name foo removed from >udd>m>Smi th>ol dseg . 

If the existing entry has only one name, wording of the query depends on the existing 
entry's type: 

caller: Do you want to delete the old segment <path>? 
caller: Do you want to delete the old multisegment file <path>? 
caller: Do you want to unlink the old link <path>? 
(Target <path2> exists.) 

or: (Target <path2> does not exist.) 

or: (Cannot get info for target <path2>.) 

or: (No target pathname.) 

The following entry points have the same calling sequence. 



Entry: nd handler $del 

This entry point queries whether or not to delete the existing entry, regardless of 
whether or not it has additional names. 



Entry: nd handler Sdel force 

This entry point deletes the old entry (no query), regardless of whether it has 
additional names. 



2-626 



AG93-05 



nd_handler_ 

Entry: nd handler $force 

This entry point deletes the existing entry if 
query. 



numeric_to_ascii. 



it has only one name, rather than issue a 



Name: numeric to ascii 

The numeric_to_ascii_ subroutine formats a real decimal floating-point number. 
Integer, fractional, or exponential format is used depending on the number being 
formatted. The value returned by this function is a varying character string that can 
contain an optional minus sign, from 1 to 59 decimal digits, and, in some cases, an 
exponent field. The caller can control the number of digits placed in the string. 

For numbers based in a number system other than base 10. use the numeric_to_ascii_base_ 
subroutine. 

USAGE 

declare numer i c_to_asc i i_ entry (float dec (59) » fixed bin) returns 
(char (72) vary i ng) ; 

result = numer i c_to_asc i i_ ((value), precision); 

ARGUMENTS 

value 

is the value to be formatted. (Input) The PL/I compiler converts to float dec(59) 
if the attributes of value are different The extra pair of parentheses around 
value suppresses the warning message about the conversion that would normally be 
generated. 

precision 

controls the number of digits placed in the output string. (Input) If precision is 
equal to 0, from 1 to 59 digits are placed in the result string depending on the 
value being formatted. If precision is less than 0, the decimal value is truncated 
to the specified number of digits. If precision is greater than 0, the decimal 
value is rounded to the specified number of digits. In the cases where precision 
is not 0, no more than the specified number of digits are placed in the output 
string. 

result 

is the character-string representation of value; it contains no blanks. (Output) 



2-627 



AG93-05 



numeric_to_ascii_ numeric_to_ascii_base_ 



NOTES 

To convert integers, use the PL /I sequence: 
result = ltrim (char (value)); 

If precision equals 0, 59 is used for the precision. In the following discussion, P is 
equal to min (59, precision). 

A number in integer format consists of a string of from 1 to P decimal digits 
without a decimal point. Integer format is used for integers whose absolute value is 
less than 10* *P. 

A number in fractional format consists of from 1 to P decimal digits with a decimal 
point. Trailing zeros in the fractional part are omitted; a number less than 1 has a 0 
to the left of the decimal point. Fractional format is used for nonintegers that can 
be exactly represented in this format. 

A number in exponential format appears as: 

xey or xe-y 

where x is a number greater than 1 and less than 10 in fractional format and y is a 
power of 10 such that the numeric value being formatted is x*10**y. Exponential 
format is used whenever integer or fractional format cannot be used. 



Name: numeric to ascii base 

The numeric_to_ascii_base_ subroutine formats a real decimal floating-point number 

based in any number system from 2 to 16. For numbers in base 10, use the 
numeric_to_ascii_ subroutine. See numeric_to_ascii_ for details. 

USAGE 

declare numer i c_to_asc i i_base_ entry (float dec (59) > fixed bin, 
fixed bin) returns (char (72) varying); 

result = numer i c_to_asc i i_base_ ((value), precision, base); 

ARGUMENTS 

value 

is the value to be formatted. (Input) 
precision 

controls the number of digits placed in the output string. (Input) 



2-628 



AG93-05 



numeric_to_ascii_base_ numeric_to_ascii_base_ 



base 

is the radix of the number system in which the result is to be represented. 
(Input) For example, a base of 2 produces a binary representation, a base of 10 
produces decimal, and a base of 16 produces hexadecimal. Bases from 2 through 
16 are allowed. 

result 

is the character-string representation of value; it contains no blanks. (Output) 
NOTES 

If precision equals 0, 59 is used for the precision. In the following discussion, P is 
equal to min (59, precision). 

A number in integer format consists of a string of from 1 to P decimal digits 
without a decimal point. Integer format is used for integers whose absolute value is 
less than 10**P. 

A number in fractional format consists of from 1 to P decimal digits with a decimal 
point. Trailing zeros in the fractional part are omitted; a number less than 1 has a 0 
to the left of the decimal point. Fractional format is used for nonintegers that can 
be exactly represented in this format. 

A number in exponential format appears as: 
xey or xe-y 

where x is a number greater than 1 and less than 10 in fractional format and y is a 
power of 10 such that the numeric value being formatted is x*10**y. Exponential 
format is used whenever integer or fractional format cannot be used. 

When the result is represented in base 16, the following characters are used to express 
the result: 

0123^56789abcdef 

When the result is represented in another base N, the first N characters from this list 
are used to express the result. 
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Name: object info_ 

The object_info_ subroutine returns structural and identifying information extracted 
from an object segment. It has three entry points returning progressively larger 
amounts of information. All three entry points have identical calling sequences, the 
only distinction being the amount of information returned in the structure described in 
"Information Structure" below. 



Entry: object info__$brief 

This entry point returns only the structural information necessary to locate the object's 
major sections. 

USAGE 

declare object_i nf o_$br I ef entry (ptr , fixed bin(2n), plr, 
fixed bin (35)) ; 

,ii „u : *- : _ .e _ (l-:.x I ~ 4 1 ■ _ jc _ _ j 1 _ \ . 

v.a 1 1 uuj c<- l_ 1 1 1 1 \j y> u 1 ici \scy_pn , uu, iiiiu , Luuej ; 

ARGUMENTS 
seg_ptr 

is a pointer to the base of the object segment. (Input) 

be 

is the bit count of the object segment. (Input) 
info_ptr 

is a pointer to the info structure in which the object information is returned. See 
"Information Structure" later in this description. (Input) 

code 

is a standard status code. (Output) 



Entry: object info__$display 

This entry point returns, in addition to the information returned in the object_info_$brief 
entry point, all the identifying data required by certain object display commands, such 
as the print_link_info command. 

USAGE 

declare object_i nf o_$d i spl ay entry (ptr, fixed bin (24), ptr, 
fixed bin (35)) ; 

call object_i nf o_$d i spl ay (seg_ptr, be, info_ptr, code): 
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ARGUMENTS 

The arguments are the same as for the object_info_$brief entry point above. 



Entry: object info Slong 

This entry point returns, in addition to the information supplied by the object_info_$display 
entry point, the data required by the Multics binder. 

USAGE 

declare object_i nf o_$ 1 ong entry (ptr, fixed bin(24), ptr, 
fixed bin (35) ) ; 

call object_i nf o_$ 1 ong (seg_ptr, be, info_ptr, code); 
ARGUMENTS 

The arguments are the same as in the object_info_$brief entry point above. 



INFORMATION STRUCTURE 

The information structure is as follows (as defined in the system include file 
object_inf o.incl.pll): 



object info 


al i gned based, 


2 


vers i on_number 


fixed bin, 


2 


textp 


ptr, 


2 


def p 


ptr, 


2 


1 i nkp 


ptr, 


2 


statp 


ptr, 


2 


symbp 


ptr, 


2 


bmapp 


ptr, 


2 


ting 


fixed bin (18) , 


2 


ding 


fixed bin (18) , 


2 


1 Ing 


fixed bin (18) , 


2 


i 1 ng 


fixed bin (18) , 


2 


s 1 ng 


fixed bin (18) , 


2 


bl ng 


fixed bin (18) , 


2 


format , 






3 old_format 


bi t (1) unal i gned, 




3 bound 


bi t (1) unal i gned, 




3 relocatable 


bi t (1) unal i gned, 




3 procedure 


bi t (1) unal i gned, 




3 standard 


bi t (1) unal i gned, 




3 gate 


bi t (1) unal i gned, 




3 separate_stat i c 


bi t (1) unal i gned, 




3 1 i nks_i n_text 


bi t (1) unal i gned, 
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3 perprocess_stat i c bit(l) unaligned, 

3 pad bit (27) unaligned, 

2 entry_bound fixed bin, 

2 textl i nkp ptr , 



/♦This is the limit of the $brief info structure.*/ 



2 compi 1 er 
2 compi 1 e_t i me 
2 userid 
2 cvers 

3 offset 

3 length 
2 comment 

3 offset 

3 length 
2 source_map 



char (8) al igned, 
f i xed bi n (71) , 
char (32) al igned, 
al i gned, 

bi t (18) unal i gned, 
bi t (18) unal igned, 

al igned, 
bi t (18) unal i gned, 
bi t (18) unal igned, 
fixed bin, 



/♦This is the limit of the $display info structure.*/ 

2 rel_text ptr, 

2 rel_def ptr, 

2 rel_l i nk ptr , 

2 rel_static ptr, 

2 rel_symbol ptr, 

2 text_boundary fixed bin, 

2 stat i c_boundary fixed bin, 

2 def aul t_truncate fixed bin, 

2 opt i onal_truncate fixed bin; 



/♦This is the limit of the $long info structure.*/ 
STRUCTURE ELEMENTS 



version_number 

is the version number of the structure (currently this number is 2). This value is 
input. 

textp 

is a pointer to the base of the text section. 

defp 

is a pointer to the base of the definition section, 
linkp 

is a pointer to the base of the linkage section. 

statp 

is a nointer to the base of the static section. 
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symbp 

is a pointer to the base of the symbol section, 
bmapp 

is a pointer to the break map. 

ting 

is the length (in words) of the text section. 

ding 

is the length (in words) of the definition section. 

ling 

is the length (in words) of the linkage section. 

ilng 

is the length (in words) of the static section. 

sing 

is the length (in words) of the symbol section. 

blng 

is the length (in words) of the break map. 

old_format 

indicates the format of the segment 
*T'b old format. 
"0"b new format. 

bound 

indicates whether the object segment is bound. 
"l"b it is a bound object segment. 
"0"b it is not a bound object segment 



relocatable 

indicates whether the object is relocatable. 

'T'b the object is relocatable. 

"0"b the object is not relocatable. 

procedure 

indicates whether the segment is a procedure. 

'T'b it is a procedure. 

"0"b it is nonexecutable data. 



standard 

indicates whether the segment is a standard object segment 
"l"b it is a standard object segment 
"0"b it is not a standard object segment 
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gate 

indicates whether the procedure is generated in the gate format. 
"l"b it is in the gate format. 
"0"b it is not in the gate format. 

separate_static 

indicates whether the static section is separate from the linkage section.. 
"l"b static section is separate from linkage section. 
"0"b static section is not separate from linkage section. 

links_in_text 

indicates whether the object segment contains text-embedded links. 

"l"b the object segment contains text-embedded links. 

"0"b the object segment does not contain text-embedded links. 

perprocess_static 

indicates whether the static section should be reinitialized for a run unit. 
"l"b static section is used as is. 
"0"b static section is per run unit. 

pad 

is currently unused. 

entry_bound 

is the entry bound if this is a gate procedure. 

textlinkp 

is a pointer to the first text-embedded link if links_in_text is equal to "l"b. 
This is the limit of the info structure for the object_info_$brief entry point, 
compiler 

is the name of the compiler that generated this object segment 

compile_time 

is the date and time this object was generated. 

userid 

is the access identifier (in the form Person_id.Project_id.tag) of the user in whose 
behalf this object was generated. 

c vers, offset 

is the offset (in words), relative to the base of the symbol section, of the aligned 
variable length character string that describes the compiler version used. 

cvers. length 

is the length (in characters) of the compiler version string. 
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comment.offset 

is the offset (in words), relative to the base of the symbol section, of the aligned 
variable length character string containing some compiler-generated comment. 

commenUength 

is the length (in characters) of the comment string. 

source_map 

is the offset (relative to the base of the symbol section) of the source map. 
This is the limit of the info structure for the object_info_$display entry point 
rel_text 

is a pointer to the object's text section relocation information. 
rel_def 

is a pointer to the object's definition section relocation information. 
rel_link 

is a pointer to the object's linkage section relocation information. 
rel_static 

is a pointer to the object's static section relocation information. 
rel_symbol 

is a pointer to the object's symbol section relocation information. 
text_boundary 

partially defines the beginning address of the text section. The text must begin on 
an integral multiple of some number, e.g., 0 mod 2, 0 mod 64; this is that 
number. 

static_boundary 

is analogous to text_boundary for internal static. 

default_truncate 

is the offset (in words), relative to the base of the symbol section, starting from 
which the symbol section can be truncated to remove nonessential information 
(e.g., relocation information). 

optional_truncate 

is the offset (in words), relative to the base of the symbol section, starting from 
which the symbol section can be truncated to remove unwanted information (e.g., 
the compiler symbol tree). 
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Name: ocu 

The ocu_ subroutine allows generation of standard format object segments and 
multi-segment files. The information is emitted via calls to ocu_ entrypoints and 
stored in internal tables until the invocation is closed, at which time the object is 
created and the sections assembled and linked together properly. 



Entry: ocu Sbackpatch 

It is often necessary in the creation of an object segment to generate a reference to 
something which has not been emitted yet. This entrypoint allows changes to be made 
in a word which has already been emitted. Since many sections of the object segment 
are being synthesized by ocu_ from other information, it is not practical to patch 
them. (eg. the definition section contains type_pairs, expression_words, init_info, and 
ACC_strings generated as byproducts of link generation. The offsets of these items are 
not known until the object is closed.) This entry is primarily for patching sections 
which were emitted as blocks of words, (ie. text, static, and symbol sections.) 

USAGE 

del ocu_$backpatch entry (ptr, char (*) , fixed bin (18) unsigned, 
char (*) , f i xed bin (35) ; 

call ocu_$backpatch (ocu_datap, section, offset, side, new__value) ; 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

section 

is a character identifying the section to be patched. (Input) 
Valid values for this argument are: 
"text" to patch the text section, 

"static" to patch the static section, 

"symbol" to patch the symbol section. 
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offset 

is the word offset within the given section of the half word to be patched. 
(Input) 

side 

is a string indicating what portion of the specified word is to be patched. (Input) 
Valid values depend on the section being patched and correspond to the valid 
types of relocation allowed for that section. 

- Text section 

"left 15 unsigned" 
"left 15 signed" 
"left 18 unsigned" 
"left 18 signed" 
"right 18 unsigned" 
"right 18 unsigned" 

- Static section 

"left 18 unsigned" 
"left 18 signed" 
"right 18 unsigned" 
"right 18 signed" 

- Symbol section 

"left 18 unsigned" 
"left 18 signed" 
"right 18 unsigned" 
"right 18 signed" 

new_value 

is the new value to be patched into the specified portion of the word. (Input) 



Entry: ocu Sclose 

takes the information provided by previous calls to ocu_ and assembles the final 
object segment The relocation information, object_map, linkage header, definition 
string map, hash table, and header are synthesized at this point 

USAGE 

del ocu_$close entry (ptr, fixed bin (35))* 
call ocu_$ close (ocu_datap, code); 

ARGUMENTS 
ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 
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code 



is a standard status code. (Output) 



Entry: ocu_$create__msf 

Creates component 0 of an object MSF. Given an array of pointers to all of the 
components of a MSF (excepting component 0), generates component 0, copying the 
external definitions, and building the first reference trap. 



del ocu_$create_msf entry (ptr, fixed bin (15) unsigned, ptr, 
fixed bin (35)) ; 

call ocu_$create_msf (component_l i stp, component_count , gen_infop, 
code) ; 

ARGUMENTS 



is a pointer to an array of pointers of dimension (l:component_count-l). (Input) 
Each pointer points to one component of the MSF. Each of the pointers points 
to a completed object segment. It is assumed that each of the components already 
has it's linkage section built as a MSF (ie. containing appropriate partially-snapped 
links) and that the msf_map is present in the definition section. 

component_count 

is the number of components in the final MSF not counting component 0. 



gen_infop 

is a pointer to the gen_info structure used to set the generator_info in the 

symbol header of component 0. (Input) The gen_info structure is declared in the 
include file ocu_dcls.incl.pll. 



USAGE 




(Input) 



del 01 gen__info 



02 gen_created 
02 generator 
02 gen_number 
02 gen_version 



al igned based, 

fixed bin (71) , 

char (8) , 

fixed bin, 

char (512) varying; 



gen_created 

is the clock time that the generator was created. 



generator 



is the name of the generator (eg. PL/ 1, binder, etc.). 
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gen_number 

is the version number of the generator. This value must the version number 
if the gen_version string. 

gen_version 

is a version string giving the name, version, and date of the generator (eg. 
Multics PL/I Compiler, Release 28e, of February 14, 1985) 

code 

is a standard status code. (Output) 



Entry: ocu $emit definition 

Emits a single non-class-3 definition, and threads it into the definition list. 
Definitions are threaded in the order of the calls to ocu_$emit_definition and 
ocu_$emit_segname. Successive calls to emit_segname generate multiple segnames in a 
single block. Calls to emit_segname with intervening calls to emit_definition create a 
new block. 

USAGE 

del ocu_$emi t_def i ni t ion entry (ptr, char (*) varying, 
fixed bin (3), fixed bin (18) unsigned, 
bit (*) ) returns (fixed bin (18) unsigned); 

def_relp = ocu_$emi t_def i ni t ion (ocu_datap, name, section, offset, 
flags) ; 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

name 

is the name of the definition. (Input) 
section 

is the section that the definition refers to. (Input) Constants for the sections can 
be found in definition_dcls.incl.pll. Valid sections for this subroutine are: 

CCPTinkl TCYT - n 
<«kvii ivn i u A i — w 

SECTIONJJNK = 1 
SECTION_SYMBOL = 2 
SECTION_STATIC = k 

offset 

is the offset of the target of the definition within the given section. (Input) 
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flags 

is a bit string representing the flags to be set in the definition. (Input) 
Constants definition the values can be found in ocu_dcls.incl.pll. 

DEF I N I T I ON_F L AGS_ I GNORE = "1000"b 
DEF I N I T I ON_F LAGS_ENTRY = "0100"b 
DEF I N I T I ON_FLAGS_RETA I N = "0010"b 
DEFINITION FLAGS INDIRECT = "0001"b 



def_relp 

is an offset to the generated definition relative to the base of the definition 
section. (Output) 



Entry: ocu Semit firstref trap 

Adds a firstref trap to the first reference trap block in the linkage section. The links 
reference by the call_relp and info_relp must have already been emitted. Errors 
encountered are reported using the sub_err_ subroutine. 

USAGE 

del ocu_$emi t_f i rstref_trap entry (ptr, fixed bin (18) unsigned, 
fixed bin (18) unsigned); 

call ocu_$em i t_f i r stref _trap (ocu_datap, call_relp, info_relp); 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

call_relp 

is the offset relative to the base of the linkage section of a link to be used to 
call the trap procedure. (Input) 

info_relp 

is the offset relative to the base of the linkage section of a link to be passed to 
the trap procedure. If this value is 0, no parameter will be passed to the trap 
procedure. (Input) 
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Entry: ocu $emit link 

Creates a single external link. The expression word, type_pair, segname and offsetname 
strings, and any trap_words or external initialization information in the definition 
section are also generated as required. Errors encountered are reported using the 
sub_err_ subroutine. 

USAGE 

del ocu_$emi t_l i nk entry (ptr, fixed bin (3), fixed bin (3), 

char (*) var, char (*) var, fixed bin, bit (6), ptr) 

returns (fixed bin (18) unsigned); 

link_relp = ocu_$emi t_l i nk (ocu_datap, type, class, segname, offsetname, 
expression, modifier, init_infop); 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

type 

is the type of the link. Constants for the valid link types can be found in 
definition_dcls.incl.pll. Valid valued are: 

1 

3 
k 

5 
class 

is the class of the link for type 1 (link self base) and type 5 (link self 
offsetname). This indicates what section of the object segment the expression 
value is relative to. It is used only if the type is 1 or 5. Constants usable for 
this value are declared in definition_dcls.incl.pll. Valid values are: 

0 
1 
2 
h 
5 

r 
O 

segname 

is the segname of the link target. This field is only used if the type of the link 
is type 3 (link-ref name-base) or type 4 (link-refname-offsetname). This is the 
refname that will be used to search for the segment when the link is snapped. 
(Input) 



L I NK_SELF_BASE 

LINK_REFNAME_BASE 

L I NK_REFNAME_OFFSETNAME = 

LINK SELF OFFSETNAME 



CLASSJTEXT 

CLASS_L I NKAGE = 

CLASS_SYMBOL = 

CLASS STATIC = 

CLASS~SYSTEM = 

CLASS HEAP = 
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offsetname 

is the name of the definition to be searched for when the link is snapped. This 

field is only used if the link type is type 4 (link-refname-offsetname) or type 5 
(link-self -offsetname). (Input) 

expression 

is a word offset to be added to the offset derived from the section and 
offsetname values. (Input) 

modifier 

is the modifier of the link. This is the modifier that will be present in the 

pointer representing the snapped link. Generally a null modifier 0"'b) is used. 
(Input) 

init_infop 

is a pointer to the initialization info, or to a trap_pair. (Input) 
If the link is a type 5, class 5 link (a *system or external link) or a type 5, 
class 6 link (a *heap link), this points to an initialization info block which will 
be placed into the definition section. This can point to any type of standard 
initialization info (INIT_NO_INIT, INIT_COPY_INFO, INIT_DEFINE_AREA, 
INI T_LIST_TEM PLATE, or INIT_DEFERRED if the object segment being created 
is an MSF component.) If the link is not a *system or *heap link, a non-null 
value will be assumed to point to a trap-pair representing a trap-bef ore-link. 
Since trap-bef ore-links are generally obsolete, this should only be non-null when 
supplying initialization_info for *system or *heap links. 

link_relp 

is the offset of this link relative to the base of the linkage section. Note that 
the link offset returned is the location of the link assuming there is no 
linkage-resident static section. When the object is closed (via a call to ocu_$close) 
all link references will be relocated to account for the presence of a static 
section. If you plan to use this returned link offset for purposes other than to 
store in one of the other object sections, you will have to adjust for the static 
section manually. 



Entry: ocu $emit partial link 

Emits an MSF partially snapped link. A partially snapped link uses no information in 
the definition section, and is snapped before entry by a first reference trap. This 
entrypoint should ONLY be called when generating a MSF component. Errors are 
reported using the sub_err_ subroutine. 
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USAGE 

del ccu_$emi t_part i al_l i nk entry (ptr, fixed bin (15) unsigned, 
fixed bin (3) » fixed bin (18) unsigned, bit (6)) 
returns (fixed bin - (1 8) unsigned); 

link__relp = ocu__$emi t_J i nk (ocu_datap, component, section, offset, 
modifier) ; 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

component 

is the component number of the target component within the MSF. Generally this 
will be in the range 1 to the maximum component number. (Input) 

section 

is the target section of the link within the target MSF component. (Input) 
Constants for these values can be found in definition_dcls.incl.pll. Valid values 
are: 

SECTION_TEXT = 0 
SECT! ON_L I NKAGE = 1 
SECTION_SYMBOL = 2 
SECTION_STAT! C = k 

offset 

is the offset of the pointer. This value is relative to the base of the section 
specified by the section parameter. (Input) 

modifier 

is the modifier of the link. This will also be the modifier of the pointer 
generated by snapping the link. The null modifier (""b) is generally used. (Input) 

link_relp 

is the offset of the generated link relative to the base of the linkage section. 
Note that this value is calculated as if there were no static section resident in the 
linkage section. When the object is closed (via a call to ocu_$close) all linkage 
references are relocated to adjust for the presence of a static section. If the 
caller wishes to use this value for other purposes that to include in another call 
to ocu_, it will have to be adjusted for the presence of the static section 
manually. (Output) 
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Entry: ocu_$emit segname 

Emits a single class-3 (segname) definition, and threads it into the definition list. The 
definitions are chained in the order of calls to ocu_$emit_definition and 
ocu_$emit_segname. Sequential calls to emit_segname generate multiple segnames in a 
single block. A call to emit_segname after calls to emit_definition starts a new block. 
It is invalid to call emit_definition without calling emit_segname at least once. 

USAGE 

del ocu_$emi t_segname entry (ptr, char (*) varying, bit (*) ) 
returns (fixed bin (18) unsigned); 

def_relp = ocu_$emi t_segname (ocu_datap, name, flags); 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

name 

is the name of this segname definition. (Input) 

flags 

is a bit string representing the flags to be set in the definition. (Input) 
Constants definition the values can be found in ocu_dcls.incl.pll. 

DEF I N I T I ON_FLAGS_J GNORE = "1000"b 

DE F I N I T I ON_F LAGS_ENTRY = "OlOCV'b 

DEF I N IT I ON_FLAGS_RETAI N = "0010"b 

DEF I N I T I ON_F LAGS_I ND I RECT = "OOOT'b 

def_relp 

is an offset to the generated definition relative to the base of the definition 
section. (Output) 



Entry: ocu__$emit__static 

Emits a block of words which are appended to the static section. Since there is no 
relocation info for the static section (and it is forced to be absolute if it is contained 
in the linkage section), no relocation information is required. Note that even if the 
static section is to be contained in the linkage section, references to the static section 
should be made with static relocation info and not attempt to adjust the offsets for 
the presence of the linkage header, when the new object is closed, all static references 
will be mapped into the appropriate linkage references. Error encountered are reported 
using the sub_err_ subroutine. 
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USAGE 

del ocu_$emi t_stat i c entry (ptr 5 ptr, fixed bin (18) unsigned, 
returns (fixed bin (18) unsigned); 

static_relp = ocu_$emi t_stat i c (ocu_datap, staticp, word_count) ; 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

staticp 

is a pointer to an array or words of dimension (word_count) to be appended to 
the static section. (Input) 

word_count 

is the number of words to be appended to the static section. (Input) 
static_relp 

is the offset of the block or words relative to the base of the static section 



Entry: ocu $emit symbol 

Emits a block of symbol words and appends them to the symbol section. Errors 
encountered are reported using the sub_err_ subroutine. 

USAGE 

del ocu_$emi t_symbo1 entry (ptr, ptr, ptr, fixed bin (18) unsigned) 
returns (fixed bin (18) unsigned); 

symbol_relp = ocu_$emi t_symbol (ocu_datap, symbolp, relocationp, 
word_count) ; 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

symbolp 

is a pointer to an array symbol section words of dimension (word_count) to be 
appended to the symbol section. (Input) 
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is a pointer to a character string of length (2*word_count) representing the 
relocation information for the accompanying block of words. (Input) 
The relocation characters are taken from the set of standard characters used by 
language translators (see the Multics Programmers Reference Manual). The 
relocation string is required even if the object to be generated is not relocatable^ 
since the relocation information is used to locate static and linkage references 
which will have to be relocated if the static section is linkage resident. 

word_count 

is the number of symbol words to be emitted. (Input) 
symbol_relp 

is the offset of this block of words relative to the base of the symbol section. 
(Output) 



Entry: ocu Semit text 

emits a block of text words, appending them to the end of the text section and 
returning the offset within the text section. Errors encountered are reported using the 
sub_err_ subroutine. 

USAGE 

del ocu_$emi t_text entry (ptr, ptr, ptr, fixed bin (18) unsigned) 
returns (fixed bin (18) unsigned); 

text_relp = ocu_$emi t_text (ocu_datap, textp, relocationp, word_count) ; 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

textp 

is a pointer to an array of text words of dimension (word_count) to be appended 
to the text section. (Input) 

relocationp 

is a pointer to a character string of length (2*word_count) representing the 
relocation information associated with the text array. (Input) 
The characters used are the standard character relocation codes used by the 
translators, (see the Multics Programmers Reference Manual). This string is 
required regardless of whether the output object is to be relocatable since it is 
used to relocate linkage and static references if the static section is not separate. 
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word_count 

is the number of words of text to be emitted. (Input) 
text_relp 

is an offset to this block of words relative to the base of the section. (Output) 



Entry: ocu_$emit_msf map 

Emits the msf_map in the definition section of the new object. This entrypoint should 
ONLY be called if the object segment being generated is an MSF component. Errors 
encountered are reported using calls to the sub_err_ subroutine. 

USAGE 

del ocu_$emi t_msf_map (ptr, fixed bin (15) unsigned, 
fixed bin (15) unsigned); 

call ocu__$emi t_msf_map (ocu_datap, component__count , my_component) ; 

ARGUMENTS 

ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures needed 
to create the object segment. (Input) 

component_count 

is the number of components in the MSF, including component 0. (Input) 
my_component 

is the number of the component being generated in the range 0 to component_count 
- 1. (Input) 



Entry: ocu__$open 

Allocates and initializes the data structures used to create the object segment and 
returns a pointer used to locate the structures. 

USAGE 

del ocu__$open entry (char (*) , char (*) , bit (*) , ptr, 
f ixed bin (35) ) » 

call ocu_$open (dir_name, entry_name, flags, ocu_datap, code); 

ARGUMENTS 

dir_name 

is the name of the directory in which the final object will be created. (Input) 
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entry_name 

is the entry name of the output object segment. (Input) 

flags 

is a bit string indicating various options to be used in the creation of the object 
segment. (Input) 

The following values may be used to derive the desired flag value, (found in 
ocu_dcls.incl.pll) 

OPEN_FLAGS_BOUND = "100000"b 

The object being created will have the format of a bound object (ie. one 
containing multiple translator produced objects) and is formatted according 
to the standards for bound objects. This format is not enforced by ocu_ 
and it is the responsibility of the caller to set up the object properly. 

OPEN_FLAGS_RELOCATABLE = "010000"b 

The object being created has relocation information and can be used as 
input to the binder or linkage editor. This flag is used by ocu_ to 
determine whether or not to add the relocation information to the 
linkage section of the object segment when the object is closed. 

OPEN_FLAGS_PROCEDURE = "001000"b 

The object con ts ins executable code. 

OPEN_FLAGS_SEPARATE_STATIC = "000100"b 

The object segment is to contain a static section rather than have the 
static section included in the linkage section. This flag is examined by 
ocu_ when closing the object segment to determine relocation of static 
and linkage section references and to generate the sections properly. 

OPEN_FLAGS_PERPROCESS_STATIC = "000010"b 

The static section of this object segment is not to be duplicated when 
called from within a run unit 

OPEN_FLAGS_NO_HASHTABLE = "000001"b 

Do not create a definition section hash table for this object segment. 
This is primarily used when creating either MSF components (which are 
never searched) or objects with very few entrypoints. 

ocu_datap 

is a pointer to the ocu data structures used by the other calls. (Output) 

code 

is a standard status code. (Output) 
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Entry: ocu_$release 

Releases table storage used by ocu_ when an invocation is aborted. 
USAGE 

del ocu_$rel ease entry (ptr) ; 
call ocu_$re1ease (ocu_datap) ; 
ARGUMENTS 
ocu_datap 

is a pointer returned by ocu_$open. This identifies all the data structures to be 
released. (Input) 



Name: parse file 

The parse_file_ subroutine provides a facility for parsing ASCII text into symbols and 
break characters. It is recommended for occasionally used text-scanning applications. 
In applications where speed or frequent use are important, in-line PL/I code is 
recommended (to do parsing) instead. 

A restriction of the subroutine is that the text to be parsed must be an aligned 
character string. 

The initialization entry points, parse_file_$parse_file_init_name and 
parse_file_$parse_file_init_ptr, save a pointer to the text to be scanned and a 
character count in internal static storage. Thus, only one text can be parsed at one 
time. 



Entry: parse file 

This entry point scans the text file and returns the next break character or symbol. 
Blanks, newline characters, and comments enclosed by /* and */, however, are 
skipped. 

USAGE 

declare parse_file_ entry (fixed bin, fixed bin, fixed bin(l), 
fixed bin(l)) ; 

call parse_file_ (ci, cc, break, eof ) ; 
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ARGUMENTS 
ci 

is an index to the first character of the symbol or break character. (Output). 
(The first character of the text is considered to be character 1.) 

cc 

is the number of characters in the symbol. (Output) 
break 

is set to 1 if the returned item is a break character; otherwise, it is 0. (Output) 

eof 

is set to 1 if the end of text has been reached; otherwise, it is 0. (Output) 



Entry: parse file Sparse file cur line 

This entry point returns to the caller the current line of text being scanned. This 
entry is useful in printing diagnostic error messages. 

USAGE 

declare parse__f i le_$parse_f i le_cur__l i ne entry (fixed bin, fixed bin); 

call parse_f i 1 e_$parse_f i 1 e_cur_l i ne (ci, cc) ; 

ARGUMENTS 

ci 

is an index to the first character of the line. (Output). (The first character of 
the text is considered to be character 1.) 

cc 

is the number of characters in the line. (Output) 



Entry: parse file Sparse file init name 

This entry point initializes the subroutine given a directory and an entry point name. 
It gets a pointer to the desired segment and saves it for subsequent calls in internal 
static. 

USAGE 

declare parse_f i 1 e_$parse_f i le_i ni t_name entry (char (*) , char (*) , ptr, 
fixed bin (35)) ; 

call parse_f i 1 e_$parse_f i 1 e_J n i t_name (dir_name, entryname, ptr, code); 
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ARGUMENTS 
dir_name 

is the directory name portion of the pathname of the segment to be parsed. 
(Input) 

entryname 

is the entryname of. the segment to be parsed. (Input) 

ptr 

is a pointer to the segment. (Output) 

code 

is a standard status code. (Output). It is zero if the segment is initiated. If 
nonzero, the segment cannot be initiated. It can return any code from 
hcs_$initiate except error_table_$segknown. 



Entry: parse file Sparse file init ptr 

This entry point initializes the parse_file_ subroutine with a supplied pointer and 
character count. It is used in cases where a pointer to the segment to be parsed is 
already available. 

USAGE 

declare parse_f i 1 e_$parse_f i 1 e_i ni t_ptr entry (ptr, fixed bin); 

call parse_f i le_$parse_f i le_ini t_ptr (ptr, cc) ; 

ARGUMENTS 

ptr 

is a pointer to a segment or an aligned character string. (Input) 

cc 

is the character count of the ASCII text to be scanned. (Input) 



Entry: parse file Sparse file ptr 

This entry point is identical to the parse_file_ entry point except that a pointer (with 
bit offset) to the break character or the symbol is returned instead of a character 
index. 
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USAGE 

declare parse_f i 1 e_$parse_f i 1 e_ptr entry (ptr, fixed bin, fixed bin(l), 
fixed bin(l)) ; 

call parse_f i 1 e_$parse_f i 1 e^ptr (ptr, cc, break, eof ) ; 

ARGUMENTS 

ptr 

is a pointer to the symbol or the break character. (Output) 

cc 

is the number of characters in the symbol. (Output) 
break 

is set to 1 if the returned item is a break character; otherwise, it is 0. (Output) 

eof 

is set to 1 if the end of text has been reached; otherwise, it is 0. (Output) 
Entry: parse file Sparse file line no 

This entry point returns to the caller the current line number of text being scanned. 
This entry is useful in printing diagnostic error messages. 

USAGE 

declare parse_f i 1 e__$parse_f i 1 e_l i ne_no entry (fixed bin); 

call parse_f i le_$parse_f i 1e_l i ne_no (cl) ; 

ARGUMENTS 

cl 

is the number of the current line. (Output) 
Entry: parse__file__$parse file_set_break 

This entry point is used to define break characters. Normally, all nonalphanumeric 
characters are break characters (including blank and newline). 

USAGE 

declare parse_f i 1 e_$parse_f i 1 e_set_break entry (char(»)); 
call parse__f i 1 e_$parse_f i 1 e_set_break (cs) 
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ARGUMENTS 
cs 

is a control string. (Input). Each character found in cs is made a break 
character. 



Entry: parse file Sparse file unset break 

This entry point renders break characters as normal alphanumeric characters. It is not 
possible to unset blank, newline, or comment delimiters, however. These are always 
treated as break characters. 

USAGE 

dec 1 areparse_f i 1 e_$parse_f i 1 e_unset_break entry (char(*)); 
call parse_f i 1 e_$parse_f i 1 e_unset_break (cs) ; 
ARGUMENTS 
cs 

is a control string, each character of which is made a nonbreaking character. 
(Input) 

EXAMPLES 

Suppose the file zilch in the directory dir_name contains the following text: 

name: foo; /*foo program*/ 

pathname: >bar; 

1 i nkage; 

end; 

f i n i ; 

The following calls could be made to initialize the parsing of zilch: 

call parse_f i 1 e_$parse_f i 1 e_i ni t_name (dir_name, zilch, ptr, code); 
call parse_f i 1 e_$parse_f i 1 e_unset_break (">_"); 
declare atom char (cc) unaligned based (p) ; 
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Subsequent calls to the parse_file_$parse_file_ptr entry point would then yield the 
following: 
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Name: parse io channel name 

The parse_io_channel_name_ subroutine parses a character string that is intended to be 
an IOM channel number. 

USAGE 

del parse i o_channel_name_ entry (char (>») , fixed bin (3) » fixed bin 
(8)7 fixed bin (35)7; 

call parse_i o_channel_name_ (arg, iom, channel, code); 

ARGUMENTS 

arg 

is the character string to be parsed. It must be of the format: 
tagnumber 

where tag is an IOM tag (a through d) and number is a decimal channel number 
from 0 to 63. 

iom 

is the IOM to which the channel is connected, (Output) 
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channel 



is the channel number. (Output) 



code 



is 0 if arg is a valid representation of a channel; otherwise, error_table_$bad_channel. 
(Output) 



Name: pascal util 

This subroutine provides interfaces for establishing and removing an on unit for the 
current procedure and for setting breakall mode on or off for a given Pascal text 
file. 



Entry: pascal util Sestablish on unit 

This entrypoint establishes an on unit for the current procedure (main or other). An 
on unit is used to establish a handler for an unusual occurrence (e.g., quit, 
program_interrupt, overflow, pascal_error). See the Multics Programmer's Reference 
Manual for a complete description of on units and conditions. 

If an on unit already exists for the given condition, it is replaced by this one. An on 
unit can be removed with the pascal_util_$remove_on_unit procedure; on units are 
automatically removed when the procedure exits. 



PROCEDURE establ i sh_on_uni t 

(condi tion_name : PACKED ARRAY [a..b : integer] of CHAR; 
PROCEDURE condi tion_handler) ; EXTERNAL : 

ARGUMENTS 
condition_name 

names the condition for which an on unit is established. Any leading spaces are 
removed, as are all characters after, including the first space encountered, if any. 

conditionjiandler 

procedure to be called if this condition occurs. This procedure must be exported 
or imported (it cannot be internal). 



USAGE 



$ IMPORT 



pascal__ut i 1_ (pascal) 



establ i sh_on_uni t $ 
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EXAMPLES 

establ i sh_on_uni t ( 1 program_i nterrupt ' , abort_cur rent_request_execut i on) ; 
establ i sh_on_uni t ('cleanup', clean_up_envi ronment) ; 



Entry: pascal util Sremove on unit 

This entrypoint removes an on unit in the the current procedure (main or other). An 
on unit is used to establish a handler for an unusual occurrence (e.g., quit, 
program_interrupt, overflow, pascal_error). See the Multics Programmer's Reference 
Manual for a complete description of on units and conditions. 

It is not an error if no on unit exists in the current procedure for the given 
condition. An on unit can be established using the pascal_util_$establish_on_unit 
procedure. 

USAGE 

$ I MPORT 

' pascal_ut i 1_ (pascal) 1 : remove_on_un i t $ 

PROCEDURE remove_on_uni t 

(condi tion_name : PACKED ARRAY [a..b : integer] of CHAR) 

EXTERNAL ; 

ARGUMENTS 
condition_name 

names the condition for which an on unit is removed. Any leading spaces are 
removed, as are all characters after, including the first space encountered, if any. 

EXAMPLES 

remove_on_uni t ( ' program_i nterrupt ' ) ; 
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Entry: pascal util $breakall on 

This entrypoint sets the given Pascal text file to breakall mode. Some screen 
applications may need to input characters as they are entered. Since Pascal text input 
is normally buffered line by line, use this procedure to tell Pascal I/O to use 
character-by-character input if your application so requires. It also sets Pascal I/O to 
unbuffered mode for the specified file and attempts to set the terminal to breakall 
mode. (No error is signaled if the terminal is already in this mode, or if this mode 
is not accepted). 

USAGE 

$ IMPORT 

1 pascal__ut i 1_ (pascal) : breakal l_on $ 

PROCEDURE breakal l_on 

(VAR text_file : text) ; EXTERNAL ; 

ARGUMENTS 
text_file 

the text file involved. It must be attached, but may or may not be open. 
NOTES 

If your terminal was switched to breakall mode from A breakall, it will be returned to 
A breakall when the procedure where the file is declared exits, or when 
pascal_util_$breakall_off is called for this file. 

EXAMPLES 

breakal 1_on (input) ; 



Entry: pascal util Sbreakall off 

This entrypoint resets the given Pascal text file to A breakall mode if it was put in 
breakall mode by a previous call to pascal_util_$breakall_on (otherwise it has no 
effect). It also resets Pascal I/O to buffered mode for this text file, and resets the 
terminal to breakall mode if it was switched from A breakall mode to breakall by a 
previous call to pascal_util_$breakall_on. 

/ #r> 

$ IMPORT 

1 pascal_ut i 1_ (pascal) : breakal l_off $ 

PROCEDURE breakall_off 

(VAR text file : text) ; EXTERNAL ; 
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ARGUMENTS 
text_file 

the text file involved. It must be attached, but may or may not be open. 
EXAMPLES 

breakal l__of f (input) ; 



Name: pathname^. 

The pathname, subroutine contains entry points for constructing pathnames and archive 
component pathnames given a directory name, entry name, and optionally, an archive 
component name. 

When a directory name and an entry name are combined to form a pathname, the 
result may be longer than 168 characters. If truncating the pathname doesn't matter, 
e.g. in an error message in a call to com_err_ for another, more important error, 
then use the pathname, or pathname_$component entry points. These entry points 
create an invalid pathname with the characters "PATHNAME TOO LONG" to let the 
reader know truncation occured. If truncating the pathname matters, use the 
pathname_$component_check entry point. 



Entry: pathname 

The pathname, entry point, given a directory name and an entry name, returns the 
pathname of the entry. 

USAGE 

declare pathname__ entry (char (*) , char (*) ) returns (char ( 1 68) ) ; 

path = pathname_ (dirname, entryname) ; 

ARGUMENTS 

path 

is the pathname of the entry in the given directory. (Output) 
dirname 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the entry. (Input) 
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NOTES 

If the resulting pathname is longer than 168 characters, then the last 20 characters of 

the result are set to " <PATHNAME TOO L0NG>" . 

EXAMPLES 

dirname entryname path 

> a >a 

>a>b c >a>b>c 
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Entry: pathname Scomponent 

This entry point, given a directory name, an entry name, and optionally, an archive 
component name, constructs a pathname or an archive component pathname. 

USAGE 

declare pathname_$component entry (char (*) , char (*) , char (*) ) 
returns (char (19 1 *) ) i 

path = pathname_$component (dirname, entryname, component__name) ; 

ARGUMENTS 

path 

is the pathname of the entry in the given directory, or is an archive component 
pathname. (Output) 

dirname 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the entry. (Input) 

component_name 

is the name of an archive component, or is null. (Input) 

NOTES 

If component_name is not null, the archive suffix on the entryname is optional, and 
is assumed if not specified. If component_name is not null and entryname ends with 
the archive suffix, the suffix is omitted from the returned pathname. 

If component_name is null and the resulting pathname is longer than 168 characters, 
then the last 20 characters of the pathname are set to " <PATHNAME TOO L0NG>" . If 
component_name is not null and the resulting archive component pathname is longer 
than 194 characters, then the last 20 characters of the dirname>entryname portion of 
the archive pathname are changed to " <PATHNAME TOO L0NG>" and the component_name 
remains in the pathname. 

EXAMPLES 
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Entry: pathname $component__check 

This entry point is the same as pathname_$component except a status code indicates 
truncation instead of an invalid pathname containing "PATHNAME TOO LONG". 

USAGE 

declare pathname_$component_check entry (char (*) , char (*) , char (*) , 
char (*) , fixed binary (35)); 

call pathname_$component_check (dirname, entryname, component_name, 
path, code) ; 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 

entryname 

is the entryname of the entry. (Input) 

componen t_name 

is the name of an archive component, or is null. (Input) 

path 

is the pathname of the entry in the given directory, or is an archive component 
pathname. (Output) 

code 

is a standard status code. (Output) It can be: 
error_table_$pathlong 

the pathname was truncated. 

NOTES 

If componen t_name is not null, the archive suffix on the entryname is optional, and 
is assumed if not specified. If componen t_name is not null and entryname ends with 
the archive suffix, the suffix is omitted from the returned pathname. 
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Name: phcs Sread disk label 

This entry point is used to read the label of a storage system disk drive. The label is 
described by the structure "label," in the include file fs_vol_label.incl.pll. 

USAGE 

del phcs_$read_d i sk_l abel entry (bit (3&) aligned, pointer, 
fixed bin (35)) ; 

call phcs_$read_d i sk_l abel (pvid, label_ptr, code); 

ARGUMENTS 

pvid 

is the physical volume id of the disk whose label is to be read. (Input). The 
physical volume id is used instead of the volume name because this is a ring zero 
interface, and volume names are not accessible by ring zero; hence, all ring zero 
interfaces that reference physical volumes use the pvid. A pvname can be 
converted to a pvid by calling the subroutine mdc_$find_volname or can be 
returned by a previous call to find_partition_. 

label_ptr 

is a pointer to the user-supplied buffer in which to read the label. (Input). The 
label is 1024 words long and is described in fs_vol_label.incl.pll. 

code 

is a nonstandard status code. (Output). It can be: 
0 

indicates that the label was successfully read. 
error_table_$pvid_not_f ound 

indicates that the specified physical volume is not presently mounted, 
an integer between 1 and 10 

indicates that a physical disk error occurred while trying to read the label. 

Error messages for physical disk errors are declared in the include file 

fsdisk_errors.incl.pll, in the array fsdisk_error_message. 
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Name: pll io 

The pll_io_ subroutine is a collection of utility functions for extracting information 
about PL/ 1 files that is not available within the language itself. 



Entry: pll io Serror code 

This function returns the last nonzero status code encountered by PL /I I/O while 
performing file operations. This is a standard Multics status code and describes the 
most recent error more specifically than the PL/ 1 condition which is raised after an 
error. 

USAGE 

declare pi l_io_$error_code entry (file) returns (fixed bin (35)); 
code = pi l_io_$error_code (f i le_variable) ; 

ARGUMENTS 

file_variable 

is a PL/ 1 file value. (Input) 

code 

is the last nonzero status code associated with the file. (Output) 
NOTES 

The specific values returned by this function are subject to change. See "Handling 
Unusual Occurrences" in the Programmer's Reference Manual. 



Entry: pll io $get iocb ptr 

This function returns the I/O control block pointer for the Multics I/O System 
switch associated with an open PL/ 1 file. This pointer may be used to perform 
control and modes operations upon the switch associated with that file. 

USAGE 

declare pi l_io_$get_iocb_ptr entry (file) returns (ptr); 
iocb_ptr = pi l_i o_$get_i ocb_ptr (f i 1 e_var i abl e) ; 



2-646 



AG93-05 



pll_io_ 



prepare_mc_restart_ 



ARGUMENTS 

file_variable 

is a PL/ 1 file value. (Input) 

iocb_ptr 

is a pointer to the I/O control block for the file. (Output) 
NOTES 

Performing explicit operations via the Multics I/O System upon switches in use by 
PL/ 1 I/O is potentially dangerous unless care is taken that certain conventions are 
observed. No calls should be made that affect the data in the PL/ 1 data set being 
accessed, the positioning of the data set, or the status or interpretation of any I/O 
operations that may be in progress. In general, this limits such calls to those which 
obtain status information. 



Name: prepare mc restart 

The prepare_mc_restart_ subroutine checks machine conditions for restartability, and 
makes modifications to the machine conditions (to accomplish user modifications to 
process execution) before a condition handler returns. 

The prepare_mc_restart_ subroutine should be called by a condition handler, which was 
invoked as a result of a hardware-detected condition, if the handler wishes the process 
to: 

1. retry the faulting instruction. 

2. skip the faulting instruction and continue. 

3. execute some other instruction instead of the faulting instruction 

and continue. 

4. resume execution at some other location in the same program. 

When a condition handler is invoked for a hardware-detected condition, it is passed a 
pointer to the machine-conditions data at the time of the fault. If the handler 
returns, the system attempts to restore these machine conditions and restart the process 
at the point of interruption encoded in the machine-conditions data. After certain 
conditions, however, the hardware is unable to restart the processor. In other cases, an 
attempt to restart always causes the same condition to occur again, because the system 
software has already exhausted all available recovery possibilities (e.g., disk read 
errors). 
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Entry: prepare mc restart Sreplace 

This entry point is called to modify machine-conditions data so that the process 
executes a specified machine instruction, instead of the faulting instruction, and then 
continues normally. 

USAGE 

declare prepare_mc_restart_$repl ace entry (ptr, bit (36), fixed bin(35)); 

call prepare_mc_restart_$repl ace (mc_ptr, new_ins, code); 

ARGUMENTS 

mc_ptr 

is a pointer to the machine conditions. (Input) 
new_ins 

is the desired substitute machine instruction. (Input) 

code 

is a standard status code. If it is nonzero on return, the machine conditions 
cannot be restarted. See "Notes" below. (Output) 



Entry: prepare mc restart Sretry 

This entry point is called to prepare the machine conditions for retry at the point of 
the hardware-detected condition. For example, this operation is appropriate for a 
linkage error signal, resulting from the absence of a segment, that the condition 
handler has been able to locate. 

USAGE 

declare prepare_mc_restar t_$retry entry (ptr, fixed bin (35)); 

call prepare_mc_restart_$retry (mc_ptr, code); 

ARGUMENTS 

mc_ptr 

is a pointer to the machine conditions. (Input) 

code 

is a standard status code. If it is nonzero on return, the machine conditions 
cannot be restarted. See "Notes" below. (Output) 
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Entry: prepare mc restart $tra 

This entry point is called to modify machine conditions data so that the process 
resumes execution, taking its next instruction from a specified location. The instruction 
transferred to must be in the same segment that caused the fault. 

USAGE 

declare prepare_mc_restart_$tra entry (ptr, ptr, fixed bin(35))» 
call prepare_mc_restart_$tra (mc_ptr, newp, code); 
ARGUMENTS 
mc_ptr 

is a pointer to the machine conditions. (Input) 
newp 

is used in replacing the instruction counter in the machine conditions. (Input) 

code 

is a standard status code. If it is nonzero on return, the machine conditions 
cannot be restarted. See "Notes" below. (Output) 

NOTES 

For all entry points in the prepare_mc_restart_ subroutine, a pointer to the hardware 
machine conditions is required. The format of the machine conditions is described in 
the Programmer's Reference Manual. 

For all entry points in the prepare_mc_restart_ subroutine, the following codes can be 
returned: 

error_table_$badarg 

an invalid mc_ptr was provided. 
error_table_$no_restart 

the machine conditions cannot be restarted. 
error_table_$bad_ptr 

the restart location is not accessible. 
error_table_$useless_restart 

the same error will occur again if restart is attempted. 
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Name: print__coboI„error 

The print_cobol_error_ subroutine allows the COBOL programmer to display the cause 
and location of a runtime error. It is meaningful only when called from within a 
USE procedure in the DECLARATIVE section of a COBOL program. The error 
information displayed pertains to the error causing the current execution of the USE 
procedure. This is identical to the messages that would have been printed on the 
terminal before aborting the program (i.e., signalling the "error" condition) had no 
USE procedure been provided. 

The print_cobol_error_ entry point displays the error information through the 
user_output I/O switch. 

USAGE IN COBOL 

call "pr i nt_cobol_er ror_" . 



Entry: print cobol error $switch 

This entry point outputs the error information to a specified I/O switch. 

USAGE IN COBOL 

01 switch-name pic x (32) . 

call "pr i nt_cobol_error_$swi ten" using switch-name. 

ARGUMENTS 

switch-name 

is the name of an I/O switch that is open for output. (Input) This includes 
user_output and error_output, as well as the I/O switch associated with any open 
external COBOL file, i.e., the internal-file-name as specified in the SELECT 
clause of the ENVIRONMENT DIVISION. 



Name: print data 



Entry: print data Sprint data 

This entry point formats and prints the output of a PL/I put data statement. The 
output switch for printing may be specified, as well as various formatting options. 
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USAGE 

declare print_data_ entry (char (*) varying, ptr, fixed bin (35) ) » 
call print_data_ (put_data_str i ng , pr i nt_data__i nf o_ptr , code); 
ARGUMENTS 
put_data_string 

is the output of a PL/ 1 put data statement. Usually obtained as follows: put data 
(xxx) string (put_data_string), where xxx is a structure whose values are to be 
formatted and printed. (Input) 

prin t_data_inf o_ptr 

is a pointer to a structure which describes the formatting options to be used for 
printing the input. See Notes below. (Input) 

code 

is a system status code. (Output) 



Entry: print data $rs 

This entry point formats the output of a PL/ 1 put data statement. The result is 
returned in a string. Various formatting options may be specified. 

USAGE 

declare pr i nt_data_$rs entry (char (*) varying, ptr, char («) varying, 
fixed bin (35)) ; 

call pr i nt_data_$rs (put_data_str i ng , pr i nt_data_i nf o_ptr , 
return_str i ng, code); 

ARGUMENTS 

put_data_string 

is the output of a PL/ 1 put data statement. Usually obtained as follows: put data 
(xxx) string (put_data_string), where xxx is a structure whose values are to be 
formatted and printed. (Input) 

print_data_info_ptr 

is a pointer to a structure which describes the formatting options to be used for 
printing the input. See Notes below. (Input) 

return_string 

is a string in which the output is returned. (Input/Output) 
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code 

is a system status code. (Output) 
NOTES 

The include file pointed to by print_data_info_ptr is declared in print_data_info.incl.pll 
as follows: 

del pr i nt_data_i nf o_vers i on_l fixed bin options (constant) init (1) 

internal static; 



del 
del 



pr i nt_data_i nf o_ptr 
1 pr i nt_data_i nf o 
2 version 
2 indentation 
2 value_column 
2 output_swi tch 
2 flags, 

3 octal 

3 hex 

3 pad 
2 intervals 



ptr ; 

based (pr i nt_data_i nf o_ptr) , 

fixed bin, 

fixed bin, 

f i xed bin, 

ptr, 



bit (1) unal, 
bit (1) unal, 
bit (3^) unaligned, 
char (256) varying; 



STRUCTURE ELEMENTS 



version 

is the version of this structure. It should be set to print_data_info_version_l. 



indentation 

is the number of spaces by which structure level names are indented. 
value_column 

is the column in which the printing of values begins. The structure names are 
indented, but the values all begin in the same column, so this value should allow 
a reasonable amount of space for structure names so they don't overlap the values 
column. 



output_switch 

is the output switch to use. This is ignored for the rs entry. If it is null then 
user_output is used. 

octal 

specifies that bit string values should be converted to octal. This is incompatible 
with the hex flag. The bit string value must be an integral multiple of 3 bits 
long in order to be converted, otherwise it is not converted. 

hex 

specifies that bit string values should be converted to hexadecimal. This is 
incompatible with the octal flag. The bit string value must be an integral multiple 
of 4 bits long in order to be converted, otherwise it is not converted. 



11/86 



2-650.2 



AG93-05A 



print_data 



qedx_ 



intervals 

is not currently supported and must be set to the null string (""). 



Name: qedx 

The qedx subroutine provides a subroutine interface to the Multics qedx Editor for use 
by subsystems wishing to edit arbitrary strings of ASCII text 

USAGE 

del qedx_ entry (ptr, fixed bin (35)); 
call qedx_ (qedx_i nf o_ptr , code); 
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ARGUMENTS 
qedx_info_ptr 

is a pointer to the qedx_info structure which defines the buffers initially available 
in qedx_ along with other options. See "The qedx_info structure" below, (input) 

code 

is a standard system status code. See "List of status codes" below. (Output) 
NOTES 

The caller of qedx_ does not need to print an error message when a non-zero status 
code is returned by the subroutine. Any appropriate error messages will have already 
been printed by qedx_ itself. The returned code is only intended to inform the caller 
of conditions requiring further attention. 

LIST OF STATUS CODES 



0 

editing completed successfully. 

error_table_$unimplemented_version 

qedx_ does not recognize the version of the qedx_info structure supplied by the 
caller. 

error_table_$f atal_error 

an error occured during initialization of qedx_ which prevented the user from 
performing any editing. The caller of qedx_ should abort its execution. 

error_table_$recoverable_error 

one of several non-fatal conditions were detected upon exit from qedx_. The 
exact condition is reflected to the caller in the qedx_info structure (see below). 
The caller of qedx_ must decide how to proceed after each of the possible 
conditions (e.g.: the program may decide not to update the permanent copy of 
the data being edited if the user exited via quit-force (qf)). 

NOTES ON INITIAL BUFFERS 

The qedx_info structure defines the initial environment to be presented to the user by 
qedx_. This environment includes an initial set of buffers along with their contents 
and default pathnames. The contents of these buffers can be read or written from the 
storage system from regions supplied by the caller (e.g.: the message in send_mail), or 
by using a caller supplied procedure (e.g.: to read/write abbreviation definitions). The 
caller can also request that the initial contents of one or more of these buffers be 
executed as qedx requests before reading the first request line from the user. 
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qedx_ always creates a buffer named "0" which it makes the current buffer before 
executing any requests. If the initial buffers marked for execution do not use the 
buffer (b) request to change the default buffer, buffer "0" will remain the current 
buffer when the first request line is read from the terminal. 



Each initial buffer must have a default pathname. As part of initialization, qedx_ will 
read the contents of the object specified by this default pathname into the buffer. If 
the buffer is read and written from the storage system, the default pathname must 
identify an existing segment or archive component. If the buffer is read and written 
from a caller supplied region, the default pathname may be omitted but is normally 
used as comment to describe the contents of the buffer (e.g.: "<send_mail message>") 
as the data is read directly from the caller's region. If the buffer is read and written 
by a caller supplied procedure, the default pathname must identify an existing object 
(e.g.: abbreviation definition) as defined by that procedure. 



For each initial buffer, the caller can specify whether or not the default pathname of 
the buffer is locked. If the default pathname is locked, use of the read (r) and write 
(w) requests with a pathname will never change the default pathname of the buffer 
nor cause qedx_ to consider the default pathname untrustworthy. (See "Notes on 
default pathnames" in the description of the qedx command in the Commands manual). 



With a locked default pathname, use of the read and write requests without a 
pathname will always read /write the original segment, region, or whatever (when using 
the caller's I/O module) specified by the caller of qedx_. In this case, use of the 
read request with a pathname will simply insert the contents of a segment into the 
buffer and use of the write request with a pathname will simply make a copy of the 
buffer in a segment for later use. 



Locking the default pathname is useful in cases where it would be difficult (if not 
impossible) for the user to reconstruct the default pathname. For example, in 
send_mail, buffer "0" contains the message being created. The default pathname in 
this case identifies the region supplied by send_mail and there is no mechanism by 
which the user can explicitly specify this default by a pathname. Therefore, send_mail 
locks the default pathname to insure that the write (w) request without a pathname 
will always update send_mail's copy of the message. 
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For each initial buffer which is being read and written from a caller supplied region, 
the caller can request that qedx_ automatically write the contents of the buffer into 
the region upon exit. If the user exits qedx_ via the quit-force (qf) request, however, 
the automatic write will be suppressed. If, when writing a buffer to the caller's 
region, the buffer is too long to fit in that region, qedx_ will issue a warning to the 
user and the buffer will be marked as truncated. While still in qedx_, the user can 
make any necessary changes to the buffer to shorten it sufficiently to fit within the 
caller's region. If, on exit from qedx_, there are truncated buffers, the user will be 
asked for permission to exit and actually truncate those buffers. Once again, this 
query is suppressed if the quit-force request is used. 



The qedxjnfo Structure 



The qedx_info structure and the named constants referenced below are defined in the 
include file qedx_info.incl.pll: 



del 1 qedx_info 
2 header, 
3 version 
3 edi tor_name 
3 buffer_io 
3 flags, 

k no_rw_path 

query_i f_mod i f i ed 
cal ler_does__io 
qui t_f orced 
buf f ers_truncated 
pad 

buffers 
buffers (qedx_i nf o_n_! 
3 buffer_name 
buf fer_path name 
reg i on_ptr 
reg i on_max_l th 

reg i on_i n i t sal 1 th 

region_f i nal_l th 
flags, 

k read_wr i te__reg i on 
1 ocked_pathname 
execute_buf f er 
def aul t_read_ok 
def aul t_wr i te_ok 
auto_wr i te 
truncated 
pad 



k 
h 
k 
h 
h 

3 n_t 



aligned based (qedx_i nf o_ptr) , 
char (8) , 

char (72) unal i gned, 
entry (pointer, fixed binary (35)), 

bi t (1) unal i gned, 
bi t (1) unal i gned, 
bit(l) unaligned, 
bi t (1) unal i gned , 
bi t (1) unal igned, 
bit (29) unal i gned, 
fixed binary, 
buffers refer (qedx_i nf o.n_buf f ers) ) , 
char (16) unal i gned, 
char (256) una 1 i gned , 
poi nter , 

fixed binary (21) , 
f i xed b i nary (21), 
f i xed b i nary (21), 



t (1) unal i gned, 

t (1) una 1 i gned , 

t (1) una 1 i gned , 

t (1) unal igned, 

t (1) unal i gned , 

t (1) unal igned, 

t (1) unal igned, 
t (29) unal i gned; 
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STRUCTURE ELEMENTS 
version 

identifies the version of the qedx_info structure supplied by the caller. It must 
have the value of the named constant QEDX_INFO_VERSION_l. (Input) 

editor_name 

is the name to be used by qedx_ in error messages and queries (e.g.: "send_mail 
(qedx)"). (Input) 

buffer_io 

is only used if flags.caller_does_io is set and is the procedure to be invoked by 
qedx_ to read /write buffers. See "Notes on buffer I/O" below. (Input) 

flags.no_rw_path 

specifies whether any read (r) or write (w) request within qedx_ can ever be 
given an explicit pathname. (Input) 

f lags.query_if _modif ied 

specifies whether qedx_ should query when the quit (q) request is issued and there 
are buffers which have been modified since they were last written. Initial buffers 
with the buffers.auto_write flag set are not considered as modified as they are 
always written before exit. (Input) 

flags. caller_does_io 

specifies whether qedx_ should call the buffer_io procedure above or perform 
I/O itself when reading/ writing buffers. (Input) 

flags, qui t_forced 

is set by qedx_ to "l"b to indicate that the user either used the quit-force (qf) 
request or answered "yes" to the modified buffers query in order to exit; it is set 
to "0"b to indicate that the user used the quit (q) request and there were no 
modified buffers present. (Output) 

f lags.buf f ers_truncated 

is set by qedx_ to "l"b to indicate that the final contents of one or more initial 
buffers were truncated on exit from qedx_. The buffers which were truncated are 
marked by the buffers. truncated flag. (Output) 

n_buffers 

is the number of initial buffers defined below. (Input) 
buffers 

defines the initial buffers available within this invocation of qedx_. See "Notes on 
Initial Buffers" above. 

buff ers. buf f er_name 

is the name of this buffer. (Input) 
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buf f ers.buf f er_pathname 

is the initial default pathname for this buffer. (Input) 

buf f ers.region_ptr 

is a pointer to the region where qedx_ will read and write this buffer if 
buffers.read_write_region is set. (Input) 

buf f ers.region_max_lth 

is the maximum number of characters which can be written into the above region 
if buffers. read_write_region is set. (Input) 

buf f ers.region_initial_lth 

is the number of characters present in the caller's region on entry to qedx_ if 
buffers. read_write_region is set. qedx_ will automatically read the specified 
characters into the buffer. (Input) 

buf f ers.region_f inal_lth 

is set by qedx_ to the number of characters written into the caller's region upon 
exit from qedx_ if buffers.read_write_region is set. This value will be larger than 
buffers.region_max_lth if buffers. truncated is set by qedx_. (Output) 

buf f ers.read_write_region 

specifies that qedx_ will use the caller's region to read/write the contents of this 

buffer until the user changes the default pathname. Use of this flag is 
incompatible with flags.caller_does_io. (Input) 

buf f ers.locked_pathname 

specifies that the default pathname of this buffer is locked and can not be 
changed by read (r) or write (w) requests. (Input) 

buf f ers.execute_buf f er 

specifies that the contents of this buffer should be executed as qedx requests 
before reading requests from the user. (Input) 

buf f ers.def ault_read_ok 

specifies that the read (r) request can be given without a pathname to read the 
current contents of the caller's region. This flag is ignored if flags.read_write_region 
is not set or the default pathname is not the caller's region. (Input) 

buf f ers.def ault_write_ok 

specifies that the write (w) request can be given without a pathname to write the 
buffer to the caller's region. This flag is ignored if flags. read write region is not 
set or the default pathname is not the caller's region. (Input) 
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buf f ers.auto_write 

specifies that the contents of this buffer will be written to the caller's region on 
exit from qedx_ unless the user uses the quit-force (qf) request or answers "yes" 
to the query to exit with modified buffers. (Input) 

buffers, truncated 

is set by qedx_ to "l"b if the entire contents of the buffer could not be written 
to the caller's region on exit from qedx_. (Output) 

NOTES ON BUFFER 110 

If flags.caller_does_io is set, qedx_ will invoke the caller supplied buffer_io procedure 
in order to read and write the contents of any buffer. qedx_ determines the 
pathname to which the buffer is to be read or written; the interpretation of this 
pathname is the responsibility of the caller's buffer_io procedure (e.g.: the procedure 
can use the pathname as the name of an abbreviation whose definition is to be 
read /written). 



For a read (r) request, qedx_ supplies an I/O region into which the buffer_io 
procedure should place the text copied from the object designated by the pathname; 
qedx_ will then insert this text into its proper place in the buffer. For a write (w) 
request, qedx_ copies the text from the buffer into an I/O region; the buffer_io 
procedure should then place this text into the object designated by the pathname. 



The buffer Jo Procedure 

qedx_ invokes the buffer_io procedure as follows — 
declare buffer_io entry (ptr, bit(l) aligned); 
call buffer_io (qedx_buf f er_i o_i nf o_ptr , success); 
where: 

qedx_buf f er_io_inf o_ptr 

is a pointer to the qedx_buffer_io_info structure describing the read /write 
operation to be undertaken. (Input) 

success 

is set by the buffer_io procedure to "l"b if the operation was successful and to 
"0"b if it failed. (Output) 

Note: It is the responsibilty of the buffer_io procedure to print any appropriate error 
messages if the operation does not succeed. 
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The qedx_buffer_io_info Structure 

The qedx_buffer_io_info structure and the named constants referenced below are 
defined in the include file qedx_buffer_io_info.incl.pll: 

del 1 qedx_buf f er_io_i nfo aligned based (qbii_ptr), 

2 vers i on char (8) , 

2 editor_name char (72) , 

2 pathname char (256) unaligned, 

2 buffer_ptr pointer, 

2 buf f er_max_l th fixed binary(21), 

2 buffer_lth fixed binary (21), 

2 direction fixed binary, 
2 flags, 

3 def aul t_pathname bit(l) unaligned, 

3 pad bit (35) unaligned; 



STRUCTURE ELEMENTS 



version 

identifies the version of the qedx_buffer_io_info structure supplied by qedx_. 
This version of the structure is given by the named constant 
QEDX_BUFFER_IO_INFO_VERSION_l. (Output) 

editor_name 

is the name of the editor to be used by the buffer_io procedure in any error 
messages and queries. (Input) 

pathname 

is the pathname to be read/written as determined by qedx_. (Input) 
buffer_ptr 

is a pointer to the I/O buffer allocated by qedx_. When reading from the 
pathname, the buffer_io procedure must place the text into this buffer; when 
writing to the pathname, the buffer_io procedure must take the text from this 
buffer. (Input) 

buffer_max_lth 

is the maximum size of the I/O buffer. This value is only used when reading 
from the pathname and specifies a limit on the amount of text which can be 
returned by the buffer_io procedure. (Input) 

bufferjth 

is the length of the text read/written from the pathname. When reading from 
the pathname, the buffer_io procedure must set this value to the number of 
characters read from the pathname and placed in the I/O buffer. (Output) When 
writing to the pathname, this value is set by qedx_ to the number of characters 
to be written into the pathname. (Input) 
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direction 

specifies the operation to be undertaken. If it has the value of the named 
constant QEDX_READ_FILE, the text is to be read from the pathname and 
placed into the I/O buffer. If it has the value of the named constant 
QEDX_WRITE_FILE, the text is to be written from the I/O buffer into the 
pathname. (Input) 

f lags.def ault_pathname 

is "l"b if the pathname supplied above by qedx_ is the default pathname of the 
buffer being read /written. (Input) 



Name: random 

The random_ subroutine is a random number generator with entry points that, given 
an input seed, generate a pseudo-random variable with a uniform, exponential, or 
normal distribution. The seed is an optional input argument; if it is not included in 
the call, an internal static variable is used and updated. 

There are two sets of entry points to the random_ subroutine. For one set of entry 
points, each call produces a single random number. To obtain a sequence of random 
numbers with the desired distribution, repeated calls are made, each time using the 
value of the seed, returned from a call, as the input value of the seed for the next 
call in the sequence. 

The second set of entry points returns an array with a sequence of random numbers. 
The first element of the array is generated from the input seed. The returned value 
of the seed is used to generate the next random number of the sequence. The 
modification of the input seed value occurs once for each element in the array. The 
programmer can obtain the same result by making one call to an array entry point 
having N elements or by making N calls to the corresponding single random number 
entry point. 

In addition, for the uniform and normal distributions, there are entry points that 
produce the negative random variables, either singly or as a sequence. For any given 
seed, the random variable produced is negatively correlated with that produced at the 
corresponding entry point. 
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Entry: random $exponentiai 

The random_$exponential entry point generates a positive random number. The 
sequence of random numbers has an exponential distribution with a mean of 1. The 
random number is generated by taking successive random numbers from the uniformly 
distributed sequence and applying the Von Neumann method for generating an 
exponentially distributed random variable. 

USAGE 

declare random_$exponent i a 1 entry (float bin(27)); 
call random_$exponent i al (random_no) ; 
or : 

declare random_$exponent i a 1 entry (fixed bin (35) t float bin(27)); 

call random_$exponent i al (seed, random_no) ; 

ARGUMENTS 

seed 

is the optional seed (see the random_$uniform entry point). (Input /Output) 
random_no 

is the random number that is generated. (Output) 
Entry: random Sexponential seq 

The random_$exponential_seq entry point produces an array of exponentially distributed 
random variables. 

USAGE 

declare random_$exponent i a l_seq entry ( (*) float bin (27), fixed bin); 
call random_$exponential_seq (array, array_size); 
or : 

declare random_$exponent i al_seq entry (fixed bin(35)> (*) float bin(27)* 
f i xed bin); 

call random_$exponent i al_seq (seed, array, array_size); 
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ARGUMENTS 
seed 

is the optional seed (see the random_$uniform entry point). (Input/Output) 
array (N) 

is the array of generated random numbers where N is greater than or equal to 
array_size. (Output) 

array_size 

is the number of values returned in the array, (Input) 



Entry: random $get__seed 

The random_$get_seed entry point is used to obtain the current value of the internal 
seed (see "Notes" below). 

USAGE 

declare random_$get_seed entry (fixed bin(35))» 
call random_$get_seed (seed_value) ; 
ARGUMENTS 
seed_value 

is the current value of the internal seed. (Output) 



Entry: random Snormal 

The random_$normal entry point generates a random number greater than -6.0 and 
less than 6.0. The sequence of random numbers has an approximately normal 
distribution with a mean of 0 and a variance of 1. The random number is formed by 
taking the sum of 12 successive random numbers from the uniformly distributed 
sequence and then adjusting the sum for a mean of 0 by subtracting 6.0. 

USAGE 

declare random_$norma 1 entry (float bin (27)); 
call random_$ normal (random_no) ; 
or : 

declare random_$ normal entry (fixed bin (35) » float bin (27)); 
call random_$normal (seed, random_no) ; 
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ARGUMENTS 
seed 

is the optional seed (see the random_$uniform entry point). (Input /Output) 
random_no 

is the random number that is generated. (Output) 



Entry: random Snormal ant 

The random_$normal_ant entry point generates a random number, random_ant, that is 
negatively correlated with the random_no argument produced by the random_$normal 
entry point. For any particular value of the seed: 

(random_ant + random no) =0.0 



USAGE 

declare random_$normal_ant entry (float bin(27)); 
call random_$norma l_ant (random_ant) ; 
or : 

declare random_$normal_ant entry (fixed bin(35)» float bin (27)); 

call r andom_$ norma l_ant (seed, random_ant) ; 

ARGUMENTS 

seed 

is the optional seed (see the random_$uniform entry point). (Input/ Output) 
random_ant 

is the random number that is generated. (Output) 



Entry: random $normal ant_seq 

± 11 w i axxwtv/xxx._«pxxv/x xxxa.x._aii t_5C\£ viiu j ^svsxxxi gvnvx diw a jwi^uwuw v/i ai x d.j ^iz/v, wi 

random variables with approximately normal distribution. The sequence contains the 
number of values specified in the array_size argument. These variables are negatively 
correlated with those produced by the random_$normal_seq entry point. 
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USAGE 

declare random_$normal_ant_seq entry ( (*) float bin(27), fixed bin); 
call r andom_$ norma l_ant_seq (ant_array, array_size); 
or : 

declare random_$normal_ant_seq entry (fixed bin(35)» (*) float bin(27)» 
f i xed bin); 

call r andom_$ norma l_ant_seq (seed, ant_array, array_size); 

ARGUMENTS 

seed 

is the optional seed (see the random_$uniform entry point). (Input/Output) 
ant_array (N) 

is the array of generated random numbers where N is greater than or equal to 
array_size. (Output) 

array_size 

is the number of values returned in ant_array. (Input) 
Entry: random Snormal seq 

The random_$normal_seq entry point generates a sequence of random variables with an 
approximately normal distribution. The sequence contains the number of values 
specified in the array _size argument. 

USAGE 

declare random_$normal_seq entry ( (*) float bin(27), fixed bin); 
call random_$normal_seq (array, array_size); 
or : 

declare random_$normal_seq entry (fixed bin (35) » (*) float bin (27) » 
f i xed bin); 

call random_$normal_seq (seed, array, array_size); 
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ARGUMENTS 
seed 

is the optional seed (see the random_$uniform entry point). (Input /Output) 
array (N) 

is an array of the generated random numbers where N is greater than or equal to 
array_size. (Output) 

array_size 

specifies the number of random variables to be returned in array. (Input) 



Entry: random $set seed 

The random_$set_seed entry point is used to set the value of the internal seed. This 
internal seed is used as the seed for the next call to any random_ entry point in 
which the optional argument, seed, is not provided (see "Notes" below). 

USAGE 

declare random_$set_seed entry (fixed bin (35)) 5 
call random_$set_seed (seed_val ue) ; 
ARGUMENTS 
seed_value 

is the value to which the internal seed is set. (Input) This value must be a 
nonzero positive integer. 



Entry: random Suniform 

The random_$uniform entry point generates a random number with a value between 
0.0 and 1.0. The sequence of random numbers has a uniform distribution on the 
interval 0 to 1. 

USAGE 

declare random_$uni f orm entry (float bin (27)); 
call random_$uni f orm (random_no) ; 
or : 

declare random_$un i f orm entry (fixed bin (35) » float bin (27)); 
call random_$un i f orm (seed, random_no) ; 
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ARGUMENTS 
seed 

is the optional seed (see "Notes"). (Input/Output) 
Input 

must be a nonzero positive integer; used to generate the random number. 
Output 

is the new value (modification of input value); used to generate the next 
random number of the sequence. 

random_no 

is the random number that is generated. (Output) 



Entry: random $uniform ant 

This entry point generates a uniformly distributed random number, random_ant, that is 

negatively correlated with the random_no produced by the random_$uniform entry 
point. For any particular value of the seed: 

(random ant + random no) = 1 .0 



USAGE 

declare random_$uni f orm_ant entry (float bin(27)); 
call random_$un i f orm_ant (random_ant) ; 
or : 

declare random_$un i f orm_ant entry (fixed bin(35)» float bin(27)); 

call random_$un i f orm_ant (seed, random_ant) ; 

ARGUMENTS 

seed 

is the optional seed (see the random_$unif orm entry point). (Input/Output) 
random_ant 

is the random number that is generated. (Output) 
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Entry: random_$uniform_ant seq 

The random_$uniform_ant_seq entry point returns an array, ant_array, of uniformly 
distributed random numbers that are negatively correlated with the array produced by 
the random_$uniform_seq entry point. For any particular value of the seed: 

(ant_array (i) + array (i)) = 1.0 

where the range of values for i is from 1 to array_size. 

USAGE 

declare random_$un i f orm_ant_seq entry ( (*) float bin(27), fixed bin); 
call random_$uni form_ant_seq (ant_array, array_s i ze) ; 
or : 

declare random_$uni f orm_ant_seq entry (fixed bin(35). (*) float bin(27)» 
f i xed bin); 

call random_$un i f orm_ant_seq (seed, ant_array, array_size); 

ARGUMENTS 

seed 

is the optional seed (see the random_$uniform entry point). (Input/Output) 
ant_array 

is the array of generated random numbers where N is greater than or equal to 
array_size. (Output) 

array_size 

is the number of values returned in ant_array. (Input) 
Entry: random $uniform__seq 

This entry point returns an array of random numbers from the uniform sequence. 
USAGE 

declare random_$un i f orm_seq entry ( (*) float bin (27), fixed bin); 
call random_$uni f orm_seq (array, array_size) ; 
or : 

declare random_$un i f orm_seq entry (fixed bin(35)» (*) float bin (27), 
fixed bin) ; 
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call random_$uni f orm_seq (seed, array, array_size); 

ARGUMENTS 

seed 

is the optional seed (see "Notes") (Input or Output) 
Input 

must be a nonzero positive integer; used to generate the first random number 
in the array. 
Output 

is the new value (modification of input value); used to generate the next 
random number of the sequence; the modification of the input value occurs 
array_size times. 

array (N) 

is an array of the generated random numbers where N is greater than or equal to 
array_size. (Output) 

array_size 

specifies the number of random variables to be returned in array. (Input) 
NOTES 

For all entry points (except random_$set_seed and random_$get_seed), if the optional 
argument, seed, is not provided in the call, an internal seed is used and updated in 
exactly the same manner as a seed provided by the caller. This internal seed is 
maintained as an internal static variable. At the beginning of a user's process, it has a 
default value of 4084114312. Its value is changed only by calls to random_$set_seed or 
by calls to other entry points in which the optional argument, seed, is not included. 

The value of a seed must be a nonzero positive integer so that a valid value will be 
returned for the seed and the random numbers. If 0 is used for the value of seed, 
the new value of the seed and the random numbers will be 0. If the value of a seed 
is negative, the low-order 35 bits of the internal representation are used as the seed. 
A given seed always produces the same random number from any given entry point. 
Since all entry points use the same basic method for computing the next seed, the 
distribution of the sequence produced by calls to any given entry point is maintained, 
although the input seed used may have been produced by a call to a different entry 
point In other words, the user need keep only a single value of the next seed even 
though he calls more than one of the entry points. However, in general, the different 
entry points, for any given input seed, produce different values for the next seed. 

The user may generate independent streams of random numbers by beginning each 
stream with separate initial seeds and maintaining separate values for the next seed. 

The uniformly distributed random number sequence is generated using the Tausworth 
method. The algorithm, in terms of the abstract registers A and B, is described below. 

The parameter n is one less than the number of used bits per word (for Multics. use 
n=35). The parameter rn is the amount of shift (for Multics, m=2). 
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1. Let register A initially contain the previous random number in bit positions 1 to 

n with 0 in the sign bit (position 0). 

2. Copy register A into register B and then right-shift register B m places. 

3. Exclusive-or register A into register B and also store the result back into register 

A. (Registers A and B now have bits for the new random number in positions 
m+1 to n, but. still contain bits from the old n-bit random number in 
positions 1 through m.) 

4. Left-shift register B (n-m) positions. (This places m bits for the new random 

number in positions 1 to m of register B and zeros in positions m+a through 
n.) 

5. Exclusive-or register B into register A and set the sign bit of register A to zero. 

(Register A now contains all n bits of the new random number.) 

6. To obtain a random number between 0.0 and 1.0, divide the n-bit integer in 

register A by 2**n. The contents of register A must be saved for use in 
generating the next random number. 

In the random_ subroutine, a word is considered 36 bits long including the sign bit. 
This generates a 35-bit integer random number. Since in Multics, a floating-point 
number has a 27-bit mantissa, this means different seeds may produce the same 
floating-point value; however, the interval between identical values of the integer seed 
is equal to the cycle length of the integer random number generator. In the random_ 
subroutine, a shift of 2 is used, which gives a cycle of (2**35)-l. The random 
number generating portion of the assembly language code used by the random_ 
subroutine is given below. 



equ 


shi ft, 2 


use a shift of 2 


ldq 


seed 


seed into the Q register 


qrl 


shi ft 


shift the seed right 


ersq 


seed 


exclusive-or to the seed 


ldq 


seed 


put result in the Q register 


qls 


35-shift 


shift left 


erq 


seed 


exclusive-or the previous result 


anq 


=0377777777777 


save only 35 bits 


stq 


seed 


return the value of the seed 


Ida 


seed 


load the integer value 


lde 


Ob25,du 


convert to floating point 


fad 


=0. ,du 


normalize the floating point 


fst 


random no 


return a random number 
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Name: rep 

The rcp_ subroutine is used to manage resources in the user's process. There are 
entrypoints to attach, detach, list, and get the status of resources owned by this 
process or by the system. 

Attaching a resource is a two step process, consisting of a call to rcp_$attach, and 1 
or more calls to rcp_$check_attach. The example which follows will demonstrate this 
process, as well as showing how to release the resource back to the system. 

/j'ts'o'cs'c This example will show how to attach a tape drive to this process, 
handling any errors that rcp_ may return. The procedure calling rcp_ 
should use the following include files: rcp_resource_types.incl.pll, 
rcp_devi ce_i nf o_structs . incl .pi 1 , event_wai t_channel . incl .pi 1 , and 
event_wai t_i nfo. i ncl .pi 1 . */ 

/ft We are going to attach a tape drive, requesting to have a specific volume 
mounted on it. »/ 



rcp_id = "0"b; 

event_channel = 0; 

tape ! nfo ptr — nu 11 () \ 

on cTeanup^cal 1 CLE ANuV ATTACH () ; 

allocate tape_info set (tape_i nf o_ptr) ; 
tape_ 
tape_ 
tape_ 
tape_ 
tape_ 
tape_ 
tape_ 
tape_ 



nfo.version_num = tape_i nf o_vers i on_3; 



/ft allocate device_info */ 
/ft fill in structure ft/ 



nf o . system_f 1 ag = "0"b; 

nfo.device_name = ""; 

nfo. model = 0; 

nf o.wr i te_f 1 ag = "l"b; 

nfo. speed = 125; 

nfo. density = "OOOOT'b; 



/ft not a system process ft/ 
/ft not asking for specific device ft/ 
/ft same */ 

/ft we are going to write ft/ 
/ft speed of drive ft/ 
/ft 6250 bpi */ 
/ft the tape we want ft/ 



nf o.vol ume_name = "tapeOl"; 
/ft Now we need an event channel for rcp_ to tell us when the attachment has 
been completed, ft/ 

call i pc_$create_ev_chn (event_channel , code); 
if code ~= 0 then goto ERROR; 

/ft Now that we have the structure initialized, begin the attachment, ft/ 

call rcp_$attach (DEVI CE_TYPE (TAPE_DR I VE_TYPEX) , tape_i nf o_ptr , 

event_channel , "", rcp_id, code); 
if code ~= 0 then goto ERROR; 

/ft Now we have to wait for the drive to be allocated to us, and the tape to be 
mounted, ft/ 



event_wai t_channel .channel_id (1) = event_channel ; 
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ATTACH_LOOP: 

rcp_comment = ""; 

call rcp_$check_at tach (rcp_id, tape_i nf o_ptr , rcp_comment, ioi_ld, 

ws_max, tc_max , rcp_state, code) ; 
if rcp_comment "" then 

{the program should print the rcp_comment on the user's terminal.}; 
goto ATTACH_STATE (rcp_state) ; 

The attachment has been completed. */ 
ATTACH_STATE (0) : 

goto ATTACH_COMPLETE; 

/j'oWcfc The resource has been attached, but we cannot use it yet. This can happen 
in the case of a tape or disk volume having to be mounted, etc. In this 
case, we block on an event channel and rcp_ will tell us when the 
resource is ready for use. */ 

ATTACH_STATE (1): 

call ipc_$block (addr (event_wa i t_channel ) , addr (event_wa i t_i nf o) , code); 
if code ~= 0 then goto ERROR; 
else goto ATTACH_L00P; 

There is no appropriate resource available. */ 
ATTACH_STATE (2) : 

code - error_table_$resource_unavai lable; 
goto ERROR; 

/**** An error has been encountered while processing the attachment. */ 
ATTACH_STATE (3) : 
goto ERROR; 

ERROR: 

cal 1 CLEANUP_ATTACH () ; 

{the appropriate message should be printed based upon the value of code, 
and this procedure should return.} 

ATTACH_COMPLETE : 

/* At this point, we can begin using the device through ioi_. */ 



/* Now that we have finished using the device, we must detach it. */ 

call rcp_$detach (rcp__id, "0"b, error_count, "", code); 
if code "= 0 then goto ERROR; 
free tape_info; 

call i pc_$del ete_ev_chn (event_channel , code); 
return; 
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CLEANUP_ATTACH: procedure; 

if rcp_id ~= ""b then call rcp_$detach (rcp_id, "0 n b, (0), "", (0)); 

if tape_i nf o_ptr ~= null () then free tape_info; 

if event_channel ^= 0 then call i pc_$del ete_ev_chn (event__channel , (0) ) ; 
end CLE ANUP_ATTACH ; 



Entry: rcp_$attach 

This entry point initiates the attachment of a device. The device that RCP will 
attempt to attach depends on the values found in the user supplied device_info 
structure. RCP will first see if an appropriate device is assigned to this process. If 
there is an appropriate assigned, unattached device, then RCP will use that device for 
this attachment. If there is not, RCP will attempt to assign an appropriate, available 
and accessible device to the process and use that device for the attachment. If no 
device can be found that meets the requirements, then the attachment is aborted. For 
tape and disk drives, if the specified volume is not mounted, RCP will mount the 
volume on the device. 

This entry point functions in cooperation with the rcp_$check_attach entry point. A 
call to rcp_$attach initiates the attachment but does not complete it. The caller still 
cannot successfully call IOI to perform I/O on the device being attached. The 
attachment will not be completed and the caller will not know the characteristics of 
the device that was attached until this data is returned from rcp_$check_attach. 

USAGE 

declare rcp_$attach entry (char (*) , ptr, fixed bin (71), char (*) , 
bit (36) aligned, fixed bin (35)); 

call rcp__$attach (devi ce_type, devi ce_i nf o_ptr , event_id, comment, 
rcp_id, code) ; 

ARGUMENTS 

device_type 

is a string that identifies the type of device to attach. It must be one of the 
constants defined in rcp_resource_types.incl.pll. (Input) 

device_info_ptr 

points to a structure supplied by the caller containing information about the 

device to be attached. (See below for information about the device_info 
structure.) (Input) 
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event_id 

is an event channel ID supplied by the caller. This channel will be used by RCP 

to notify the user of the progress of the attachment in some cases. For more 

information, see the example above. (Input) 

comment 

is a message to be displayed to the operator upon completion of device 
assignment and prior to any volume mounting that may be required. (Input) 

rcp_id 

is an internally generated unique id for this rep attachment. (Output) It is passed 
to other rcp_ entrypoints that manipulate the attachment. 

error_code 

is a standard system status code. (Output) Possible codes returned are: 

error_table_$bad_volid 

for a tape or disk device, a volume must be specified and it was not. 

error_table_$resource_attached 

the requested device is already attached to the requesting process. 

error_table_$no_operation 

this is a T&D operation and the privileged attach entry point rcp_priv_$attach 
must be used instead. 

error_table_$resource_unknown 

the requested device is not known to the system. 

error_table_$resource_unavailable 

the requested device was accessible but not available. 

error_table_$resource_bad_access 

the requested device was unaccessible. 

ACCESS REQUIRED 

RW access to the Access Control Segment (ACS) associated with the resource is 
required in order to attach the resource. If RCPRM is not enabled at your site, then 
the only resource controlled by RCP is the device,and access control is not provided 
for tape and disk volumes. The ACS is located in >scl>rcp>RESOURCE_NAME.acs. 

If RCPRM is enabled, then access to both devices and volumes is controlled by ACS 
segments. For reading, the user must have R effective access, and for writing, RW 
effective access. This access may be derived from an ACS segment associated with the 
resource, or based on the owner of the resource, as determined by RCPRM. Refer to 
the Reference Manual for further details. 
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NOTES 

The devicejnfo structure is a general purpose header structure used for the various of 
types of resources. It is declared is rcp_device_info_structs.incl.pll, along with the 
structures for tapes, disks, and printers. Each structure uses device_info as its header. 
The include file decribes the structures for each resource in more detail. 



del 1 devi ce_i nf o based (devi ce_i nf o_ptr) aligned, 

2 vers i or_num fixed bin, 

2 usage__time fixed bin, 

2 wait_time fixed bin, 

2 system_f 1 ag bi t (1) , 

2 device_name char (8) , 

2 model fixed bin, 

2 qual i f iers (h) fixed bin(35); 



STRUCTURE ELEMENTS 



version_num 

is the version number of this structure. This will be different for each resource 
type. (Input) 

usage_time 

number of minutes device will /may be used. (Reserved for future use.) 
wait_time 

number of minutes user will /must wait for assignment completion. (Reserved for 
future use.) 

system_flag 

if this is "Fb, the user wants to be considered a system process for this 
assignment. (Input) 

device_name 

the name of the device, (Input to rcp_$attach/ Output from rcp_$check_attach) 
model 

the model number of the device. (Output from rcp_$check_attach) 
qualifiers 

this element will contain different information for each resource type. (Input to 
rcp_$attach/ Output from rcp_$check_attach) 
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Entry: rcp_$check__attach 

This entry point establishes completion of the attach process begun by the rcp_$attach 
entry point, causes IOI to set the workspace and timeout limits for the device, 
promotes the device to the caller's validation level, and returns info needed by the 
user to perform I/O on this device. It should be noted that an attachment is not 
complete until this entry point is called. 

USAGE 

declare rcp_$check__attach entry (bit (36) aligned, ptr, char (*) , 
fixed bin, fixed bin (19) » fixed bin (71), fixed bin, 
fixed bin (35)) ; 

call rcp_$check_attach (rcp_id, devi ce_i nf o_ptr , comment, ioi_index, 
workspacejnax, timeout_max, statex, code); 

ARGUMENTS 

rcp_id 

is the unique identified for this attachment returned by rcp_$attach. (Input) 
device_info_ptr 

is a pointer to the device_info structure that was supplied to rcp_$attach when 
this attachment was begun. (Input) This entrypoint will update the information in 
this structure to reflect the characteristics of the actual device that was acquired. 

comment 

the comment associated with this attachment. This argument is always a null 
string. (Output) 

ioi_index 

is an index used for communication with IOI. (Output) 

workspace_max 

is the size of IOI workspace in words. (Output) 

timeout_max 

is the amount of time IOI will wait for another operation to begin, after an 
operation completes, before it unwires the IOI workspace. If the next operation 
begins before this time out, then the workspace remains wired. Otherwise, it gets 
unwired automatically and the next operation is delayed while IOI rewires the 
workspace pages into memory. 

statex 

is the current state of the attachment. (Output) Its possible values are: 

0 the attachment is complete 

1 the attachment is nearly complete 

2 the resource is unavailable 

3 an error occurred while attaching the resource 
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code 

is a standard system status code. (Output) Possible returned codes are: 

error_table_$bad_arg 

the rcp_id supplied is invalid. 

error_table_$invalid_state 

the attachment of this device is in the wrong state to be completed now. 

ACCESS REQUIRED 

Only the process that began the attachment with rcp_$attach can complete it with 
rcp_$check_attach, but no access is required for this entrypoint, as all access checking 
is performed by rcp_$attach. 



Entry: rep $detach 

This entry point detaches an IOI device attachment. Depending on the disposition, the 
device will also be unassigned. 

/ /c Anc 

declare rcp_$detach entry (bit (36) aligned, bit(*), fixed bin, char (*) , 
f i xed bi n (35) ) ; 

call rcp_$detach (rcp_id, disposition, error_count, comment, code); 

ARGUMENTS 

rcp_id 

unique rep identification number that identifies the attachment of the device. 
(Input) 

disposition 

specifies whether the device should be unassigned or not. (Input) Any volume 
associated with the device is always unassigned. This argument's possible values 
are: 

"i"b leave the device assigned to this process 

"0"b if the device was assigned to this process by the rcp_$attach call that 
initiated this attachment, then unassign the device; otherwise leave it 
assigned to this process. 

error_count 

user ring error count for the attachment indicating the number of errors during 
the attachment. This count is logged in the system log message for this 
detachment. (Input) 
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comment 

a comment to be displayed to the operator upon detachment of the device. 
(Input) 

code 

is a storage system status code. (Output) Possible codes returned are: 

error_table_$bad_arg 

indicates a possible invalid or incorrect repaid. 

error_table_$bad_processid 

the device was not attached to this process or the rcp_id (which reflects the 
process id which made the attachment) is invalid or incorrect. 

ACCESS REQUIRED 

Only the process which attached the device can detach it using this entry point 



Entry: rep $get status 

This entry point will find a resource given its name or UID, and return all the 
information about it depending on the user's access to the resource. 

USAGE 

declare rcp_$get_status entry (ptr, char (*) , fixed bin (35)); 
call rcp_$get_status (resource_desc_ptr , reg i stry_d i r , code); 
ARGUMENTS 
resource_desc_ptr 

is a pointer to the resource_descriptions structure, which is defined in 
resource_control_desc.incl.pll, (Input) 

registry_dir 

the absolute pathname of the directory containing the RCP registries. (Input) This 
is usually >system_control_l>rcp. 

code 

is a standard system status code. (Output) Possible codes returned are: 

*>rmr taWp tartirvn tint -r»f>rf nrmpH 

the action was not performed and the user does not have enough access to 
find out why. 

error_table_$bad_resource_spec 

there was erroneous data in the resource_descriptions structure supplied. 
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error_table_$resource_awaiting_clear 

the resource is awaiting clear and is unavailable for status. 

error_table_$not_abs_path 

the registry directory pathname supplied is not an absolute pathname. 

error_table_$resource_locked 

the resource is locked and unavailable. 

error_table_$resource_unknown 

the requested resource is unknown to the system. 

error_table_$unimplemented_version 

the version of the resource_descriptions structure supplied is not supported. 

error_table_$resource_bad_access 

the user does not have enough access to get resource's status. 

ACCESS REQUIRED 

Read effective access is required to get the status of an RCP object 
NOTES 

This entrypoint is only useful when the site has RCPRM enabled. 



Entry: rep Slist resources 

This entry point returns a list of resources owned by a specific user, by the system, 
or unowned resources. The selection of information to be returned is determined by 
the userid argument. 

USAGE 

declare rcp_$ 1 i st__resources entry (char (*) , char (*) , char (*) , ptr, 
fixed"~bin (35), ptr, fixed bin (35)); 

call rcp_$ 1 i st_resources (resource_type, reg i stry_d i r . userid, 
user_area_ptr , n_resources, return_ptr, code); 

ARGUMENTS 

resource_type 

the resource type, i.e., "tape_vol". (Input) 

registry_dir 

the absolute pathname of the directory where the RCP registries are located. 
(Input) This is usually >system_control_l>rcp. 
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userid 

contains the selection criteria for information to be returned. (Input) Its possible 
values are: 

Person.Project 

return information about the resources owned by the specified user, 
system 

return information about the resources owned by the system. 

free 

return information about the resources in the free pool. 
user_area_ptr 

pointer to the area where the resource_list structure should be allocated. See 

"Notes" below for description of the resource_list structure. (Input). 

n_resources 

number of resources in the resource_list structure returned to the user. (Output) 
return_ptr 

is a pointer to the allocated structure in the user-supplied area. (Output) 

code 

is a standard system status code. (Output) Possible codes returned are: 

error_table_$insuf f icient_access 

the user does not have enough access to find out the desired information. 
See "Access Required" below. 

error_table_$bad_name 

the userid supplied was Person.* and this is not allowed. 

error_table_$smallarg 

the user-supplied area is too small for the information to be returned. 

ACCESS REQUIRED 

R effective access is required to list the existence of a resource. This computation 
takes into account ONLY the AIM range of the resource since R raw mode is not 
necessary to list the existence of a resource, but read_allowed_ is required. 

NOTES 

This entrypoint is only useful when the site has RCPRM enabled. . 
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The resource_list structure is defined in resource_listincl.pll and is declared as follows: 

del 1 resource_l i st aligned based (resource_1 i st_ptr) , 
2 forward_ptr pointer initial (null), 
2 max_entries fixed bin, 
2 n_resources fixed bin initial (0), 
2 resource_name 

(Max_entries refer (resource_l i st .max_entr i es) ) char (32); 

STRUCTURE ELEMENTS 

forward_ptr 

points to the next block, null if there is no next block. 
max_entries 

number of elements in the resource_name array. 
n_resources 

number of valid resource names in this block. 

resource_names 

array of resource names that meet the specified criteria. 



Name: read allowed 

The read_allowed_ function determines whether a subject of specified authorization has 
access (with respect to the access isolation mechanism) to read an object of specified 
access class. For information on access classes, see the Programmer's Reference 
Manual. 

USAGE 

declare read_al lowed__ entry (bit (72) aligned, bit (72) aligned) returns 
(bit(l) aligned); 

returned__bi t = read__allowed__ (authorization, access_c 1 ass) : 

ARGUMENTS 

authorization 

is the authorization of the subject (Input) 

access_class 

is the access class of the object (Input) 
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returned_bit 

indicates whether the subject is allowed to read the object (Output) 
"l"b read is allowed. 
"0"b read is not allowed. 



Name: read passwords 

The read_password_ subroutine reads a single line from the users' terminal (actually 
from the user_input I/O switch). It attempts to hide the input line by turning the 
printing mechanism off before reading and turning it back on afterwards. If the 
printing mechanism cannot be turned off, then a mask consisting of several layers of 
printing designed to "black out" the page is printed. One of the layers of printing is 
pseudo-randomly generated so that it will be different each time the subroutine is 
called, thus making it difficult to analyze the layers of overprinting. The mask is 12 
characters long. 

USAGE 

declare read_password_ entry (char (*) , char(>'0); 
call read_password_ (prompt, password); 
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ARGUMENTS 
prompt 

is a message to be printed before the password is read. It can be any length. A 
newline character is always printed after the prompting message. (Input) 

password 

is the password that the user typed. It can be up to 120 characters long. 
(Output) 

NOTES 

The password is processed as follows: Tab characters are translated to blanks. Leading 
blanks are removed. Characters after any embedded blanks are removed. If the 
resulting password is all blank, a single asterisk ("*") is returned, otherwise the 
password is returned. 



Entry: read password Sswitch 

This entry is similar to read_password_, but it allows the caller to specify the I/O 
switches to be used to print the prompt and read the password. 

USAGE 

declare read_password_$swi tch entry (ptr, ptr, char (*) , char (*) , 
f i xed bin (35) ) ; 

call read_password_$swi tch (output_swi tch , i nput_swi tch, prompt, 
password, code) ; 

ARGUMENTS 

output_switch 

is a pointer to the I/O switch on which the prompt, and if necessary the 
password mask, is printed. (Input) 

input_switch 

is a pointer to the I/O switch from which the password is read. (Input) 
prompt 

is a message to be printed before the password is read. It can be any length. A 
newline character is always printed after the prompting message. (Input) 

password 

is the password that the user typed. It can be up to 120 characters long. 
(Output) 
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code 

is a standard system status code which is non-zero only if a password could not 
be read. (Output) 

NOTES 

The password is processed as follows: Tab characters are translated to blanks. Leading 
blanks are removed. Characters after any embedded blanks are removed. If the 
resulting password is all blank, a single asterisk ("*") is returned; otherwise the 
password is returned. 



Name: read write allowed 

The read_write_allowed_ function determines whether a subject of specified authorization 
can read, append, modify, and destroy data in an object of specified access class. For 
information on access class, see the Muitic Programmers Reference Manual, Order 
No. AG91. 

USAGE 

declare read_wr i te_al lowed_ entry (bit(72) aligned, b 1 1 (72) aligned) 
returns (bit(l) aligned); 

returned_bit = read_wr i te_a 1 1 owed_ (authorization, access_c 1 ass) ; 

ARGUMENTS 

authorization 

is the authorization of the subject. (Input) 

access_class 

is the access class of the object. (Input) 

returned_bit 

indicates whether the subject is allowed to both read and write the object. 
(Output) 

"l"b read and write are allowed. 
"0"b read and write are not allowed. 
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Name: rehash 

This subroutine rehashes (reformats into a different size) a hash table of the form 
that is maintained by the hash_ subroutine. In most cases, hash_ calls rehash_ 
automatically when a table becomes too full. For hash tables that are embedded in 
larger data bases, the data base maintainer must monitor the density of the hash table 
and call rehash_ when necessary to maintain the optimal table size. See the 
description of the hash_ subroutine for more information. 

USAGE 

declare rehash_ entry (ptr, fixed bin, fixed bin(35))» 

call rehash_ (table_ptr, size, code); 

ARGUMENTS 

table_ptr 

is a pointer to the table to be rehashed. (Input) 

size 

is the new size of the hash table. (Input). See the description of hash_$opt_size. 

code 

is a standard status code. (Output). It can be: 
0 

table rehashed successfully. 
error_table_$invalid_elsize 

size is too large. 
error_table_$full_hashtbl 

size is not large enough to hold all the entries in the current hash table. 



Name: release area 

The release_area_ subroutine cleans up an area after it is no longer needed. If the 
area is a segment acquired via the define_area_ subroutine, the segment is released to 
the free pool via the temporary segment manager. If the area was not acquired (only 
initialized) via the define_area_ subroutine then the area itself is reinitialized to the 
empty state. In certain cases when the area is defined by the system or when the 
area is extended in ring 0, the temporary segment manager is not used and the area 
segments are actually created and deleted. Segments acquired to extend the area are 
released to the free pool of temporary segments or deleted if they are not obtained 
from the temporary segment manager. 
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USAGE 

declare rel ease_area_ entry (ptr) ; 
call rel ease_area_ (area_ptr) ; 
ARGUMENTS 
area_ptr 

points to the area to be released. (Input /Output) 
NOTES 

The release_area_ subroutine sets area_ptr to null after copying it to a local variable. 



Name: release temp segment 

The release_temp_segment_ subroutine is used to return a temporary segment (acquired 
with the get_temp_segment_ or the get_temp_segments_ subroutine) to the free pool 
of temporary segments associated with the process. Through the pool concept, 
temporary segments can be used more than once during the life of a process. Since 
the process does not have to create a new segment each time one is needed, overhead 
costs are decreased. 

USAGE 

declare re 1 ease_temp_segment_ entry (char (*) , ptr, fixed bin (35)); 
call rel ease_temp_segment_ (program_name, temp_seg_ptr , code); 
ARGUMENTS 
program_name 

is the name of the program releasing the temporary segment (Input) 
temp_seg_ptr 

is a pointer to the temporary segment being released. (Input/Output) 

code 

is a standard status code. (Output) 
NOTES 

A nonzero status code is returned if the segment being released was not assigned to 
the given program. See the description of the get_temp_segment_ or the 
get_temp_segments_ subroutine for a description of how to acquire a temporary 
segment. 
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The pointer in the temp_seg_ptr variable above is set to the null value after the 
segment is successfully returned to the free pool. This fact can be used by callers to 
determine if a given temporary segment has been released. 

A null input value for the temp_seg_ptr variable is not treated as an error. No action 
is performed. 



Name: release temp segments 

The release_temp_segments_ subroutine is used to return temporary segments (acquired 
with the get_temp_segment_ or get_temp_segments_ subroutine) to the free pool of 
temporary segments associated with each user process. Through the pool concept, 
temporary segments can be used more than once during the life of a process. Since 
the process does not have to create a new segment each time one is needed, overhead 
costs are decreased. 

USAGE 

declare rel ease_temp_segments_ entry (char (*) , (*) ptr, fixed bin(35)); 

call release__temp_segments_ (program_name , ptrs, code); 

ARGUMENTS 

program_name 

is the name of the program releasing the temporary segments. (Input) 

ptrs 

is an array of pointers to the temporary segments being released. (Input/Output) 

code 

is a standard system status code. (Output) 
NOTES 

A nonzero status code is returned if any segment being released was not assigned to 
the given program. See the description of the get_temp_segments_ or the 
get_temp_segment_ subroutine for a description of how to acquire temporary segments. 

The pointers in the ptrs array above are set to the null value after the segments are 
successfully returned to the free pool. This fact can be used by callers to determine 
if a given temporary segment has been released. 

Null input values in the ptrs array are not treated as errors. No action is performed 
for them. 
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Name: request id 

Given a Multics standard clock value, this entry point returns a char(19) formatted 
date (expressed in GMT) in the form " A y c A my A dm A Hd A MH A 99. 999999UM" , e.g. 
830718105806.808512 (yymmddHHMMSS.SSSSSS) This is a request id as used by the 
absentee facility, I/O daemons, and other queue-driven facilities. 

USAGE 

declare request_id_ entry (fixed bin (71)) returns (char (1 9) ) ; 

result = request_id_ (clock); 

ARGUMENTS 

clock 

is the clock value to be formatted. (Input) 
result 

is the resultant character string. (Output) 



Name: requote string 

The requote_string_ subroutine doubles all quotes within a character string and returns 
the result enclosed in quotes. 

USAGE 

declare requote_str i ng_ entry (char (*) ) returns (char (*) ) ; 
requoted_str i ng = requote_str i ng_ (string); 
ARGUMENTS 
string 

is the string to be requoted. (Input) 
requoted_string 

is the string with all quotes doubled and enclosed in quotes. (Output) 
EXAMPLES 

"""a""" = requote_str i ng_ ("a") 

"""a"' b" ,IM = requote_str i ng_ ("a""b M ) 
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Name: resource control 

The resource_control_ subroutine provides an interface to the Multics resource control 
facility. Entry points in this subroutine allow programs to reserve or cancel I/O 
devices and volumes. 

See the Programmer's Reference Manual for a description of the Multics resource 
control facility. 



Entry: resource_control_$cancel__id__string 

This entry point cancels the reservation of a resource or group of resources. 
USAGE 

declare resource_control_$cancel_id_str i ng entry (char (*) , char (*) , 
bit(l) aligned, fixed bin (35)); 

call resource_control_$cancel_id_str i ng (reservat i on_i d , group_id, 
system, code) ; 

ARGUMENTS 

reservation_id 

is the character string representation of the reservation identifier to be cancelled. 
(Input) 

group_id 

is the group ID of the user to whom the reservation belongs. (Input). This is 
only valid if system = 'T'b. 

system 

specifies, if 'T'b, that a privileged cancellation is to be performed (see "Notes" 
below). (Input) 

code 

is a standard status code. (Output) 
ACCESS REQUIRED 

Execute access to the rcp_sys_ gate is necessary to perform a privileged cancellation. 
NOTES 

If system = 'T'b, then the reservation group is forcibly canceled whether or not it 
belongs to the current process. 
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Entry: resource control_$reserve 

This entry point reserves a resource or group of resources for use by a process. 
USAGE 

declare resource_contro1__$reserve entry (pointer, pointer, 
bit (1) aligned, bit (72) aligned, fixed bin (35))); 

call resource_control_$reserve (descr iptions_ptr , reservat i on_desc_ptr , 
authorization, system, code); 

ARGUMENTS 
descriptions_ptr 

is a pointer to the structure containing a description of the resources to be 
reserved (see "Resource Description" below). (Input) 

reservation_desc_ptr 

ir o tjQf try tVi£» ct-rl ir»tl l-r/3 rT\ntoinincr f*»c<vrv«ltiirvn infnrmntinn f r\r tVia Tornnroac 

lO U pVlUtVl W tllV on uvmiv «wiinumu|; a vuvj tu.i„ivjh nil VI U1UUU11 1 Ul LX1W 1VJUU1VW 

to be saved (see "Reservation Description" below). (Input) 
authorization 

checks the user's authorization to use the devices or volumes and is only valid if 
system = "l"b. (Input) 

system 

specifies, if "l"b, that the calling process wishes to perform a privileged 
reservation (see "Notes" below). (Input) 

code 

is a standard status code. (Output) 
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RESOURCE DESCRIPTION 



The descriptions_ptr argument points to the following structure (this structure is 
declared in the include file resource control_desc.incl.pll): 



del 1 resource_descr i pt ions 
2 version_no 
2 n_i terns 

2 item (Resource_count 
3 type 
name 
uid 

potent i a l_attr ibutes 
attr i butes 
des i red_attr i butes 
potent i al_aim_range 
a im_range 
owner 
acs__path 
1 ocat i on 
comment 
charge_type 
rew 

(usage_lock, 
release_lock, 
awaiting_clear, 
user_a 1 1 oc) 
3 pad2 

3 g i ven al i gned, 

(4 (name, 
uid, 

potent i al_attr i butes, 
desi red_attr ibutes, 
potent i a 1 _a i m_r ange, 
a im_range, 
owner , 
acs_path , 
1 ocat i on, 
comment , 
charge_type, 
usage_l ock , 
reiease_iock, 
user_al loc) bi t 

k padl bit 
3 state bit 
3 status_code 



based (resource_desc_ptr) aligned, 
f i xed bin, 
f i xed bin, 
refer (resource_descr i pt i ons . n_i terns) ) 
char (32) , 
char (32) , 
bit (36), 
bit (72) , 

(72) , 
(72) , 
(72), 
(72), 



al i gned, 



(2) 
(k) 
(2) 
(2) 
char 
char 
char 
char 
char 
bit 



bit 
bit 



bit 
bit 
bit 
bit 
(32) , 
(168) , 
(168) , 
(168) , 
(32) , 
(3) unal i gned, 



(1) unal i gned, 
(29) unal i gned, 



(1), 

(22) ) una 1 i gned , 
(36) aligned, 
f i xed bin (35) ; 
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STRUCTURE ELEMENTS 
version_no 

is the current version number of the structure. (Input). It should be set to 
"resource_desc_version_r\ 

n_items 

specifies the number of resources described by this structure. (Input). A 
consistent combination of the following elements must be supplied for each 
resource described. 

type 

specifies the type of resource desired (e.g., tape, disk_drive). (Input). It must be 
supplied (see "Notes" below). 

name 

is a specific resource name. (Input/Output). If flags. name_given = "l"b, the 
named resource is chosen. If flags. name_given - "0"b, a resource is chosen 
depending on criteria specified by other elements of the structure, and the name 
of the resource chosen is returned in this element (see "Notes" below). 

uid 

is the unique identifier of a specific resource. (Input/Output). If 
flags. uid_given = "l"b, the specified resource is chosen. If flags. uid_given = "0"b, 
a resource is chosen depending on criteria specified by other elements of the 
structure, and the unique identifier of the resource chosen is returned in this 
element. 

poten tial_attributes 

specifies the potential attributes of the resource chosen. (Output) 

attributes 

contains, if flags.attr_given = "l"b, the specification of attributes that the resource 
chosen must possess. (Input /Output). If flags.attr_given = "0"b, the resource to be 
chosen need not possess any particular attributes. The attributes of the resource 
chosen are returned in these elements (see "Notes" below). 

desired_attributes 

specifies the desired attributes of the resource chosen. (Input) 

poten tial_aim_bounds 

are a pair of AIM access classes, specifying the minimum and maximum process 
authorization that can be permitted to acquire this resource. (Output) 

aim_bounds 

are a pair of AIM access classes, specifying the minimum and maximum process 
authorization that can be permitted to read and write this resource. (Input/Output). 
If flags. aim_bounds_given = "l"b, this element is input; otherwise, it is output. 
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owner 

is the owner of the resource. (Input/Output). If flags.owner = "l"b, this element 

is input; otherwise, this element is output (see "Notes" and "Access Required" 
below). 

acs_path 

is the pathname of the Access Control Segment (ACS) for this resource (see 
"Access Required" below). (Input) 

location 

contains a character string description of the location of this resource. (Output) 
comment 

contains a character string comment that is associated with this resource. (Input) 
charge_type 

is the accounting identifier for this resource. (Input) 

rew 

is the effective access of the user to this resource. (Output) 
usagejock 

specifies, if "l"b, that this resource cannot be used by any user, regardless of the 
state of the resource. (Input) 

release_lock 

specifies, if "l"b, that the owner of the resource is not allowed to release the 

resource. (Input). Unless system = "l"b, this element is ignored (see "Notes" 
below). 

awaiting_clear 

specifies that the resource is awaiting manual clear. (Output) 
user_alloc 

specifies, if "l"b, that the user has not allocated the resource to any use. (Input) 

pad2 

is unused and must be zero. (Input) 
name 

is "l"b if item.name has been supplied by the caller. (Input) 

uid 

is "l"b if item. uid has been supplied by the caller. (Input) 
potential_attr 

is "l"b if item.potential_attributes has been supplied by the caller. (Input) 
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desired_attr 

is 'T'b if item.desired_attributes has been supplied by the caller. (Input) 

potential_aim_bounds 

is 'T'b if item.potential_aim_bounds has been supplied by the caller. (Input) 

aim_bounds 

is "l"b if item.aim_bounds has been supplied by the caller. (Input) 
owner 

is "l"b if item.owner has been supplied by the caller. (Input) 
acs_path 

is 'T'b if item.acs_path has been supplied by the caller. (Input) 
location 

is 'T'b if item.location has been supplied by the caller. (Input) 
comment 

is 'T'b if item. comment has been supplied by the caller. (Input) 
charge_type 

is "l"b if item.charge_type_given has been supplied by the caller. (Input) 
usage_lock 

is 'T'b if item.usage_lock has been supplied by the caller. (Input) 
release_lock 

is 'T'b if item.releasejock has been supplied by the caller. (Input) 
user_alloc 

is 'T'b if item.user_alloc_given has been supplied by the caller. (Input) 

padl 

is unused and must be zero. (Input) 

state 

is for the use of resource_control_ and should not be used by the user. (Output) 
status_code 

is a standard status code. (Output). If the subroutine argument code is nonzero, 
one or more items in the structure have a nonzero status_code specifying in more 
detail why the attempt to manipulate the described resource is refused. 
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ACCESS REQUIRED 

The user must have at least sm permission to the directory in which the ACS is 
specified to reside. 

Unless otherwise stated, the user must have re access to the rcp__sys_ gate to specify 
system = "l"b in the calling sequence for any entry point of the resource_control_ 
subroutine. 

NOTES 

A list of defined resource types can be obtained via the list_resource_types command. 

Suitable values for the attributes element can be constructed using the 
cv_rcp_attributes_$f rom_string subroutine. 

RESERVATION DESCRIPTION 

The reservation_desc_ptr argument points to the following structure (declared in the 
include file resource_control_desc.incl.pll): 

del 1 reservat ion_descr i ption aligned based, 
2 version_no fixed bin, 
2 reserved_for char (32) , 
2 reserved_by char (32) , 
2 reservat ion_id fixed bin (71) » 
2 group_start i ng__t ime fixed bin (71) , 
2 asap_duration fixed bin (71), 
2 f lags al i gned, 
(3 auto_expire bit (1), 

3 asap bit (1) , 

3 rel bit (1) , 

3 sec bit (1)) unaligned, 
2 n_i terns fixed bin, 

2 reservat ion_group (Resource_count refer 
(reservat i on_descr i pt i on . n_i terns) ) , 
3 starti ng_t ime fixed bin (71)* 
3 duration fixed bin (71); 

STRUCTURE ELEMENTS 

version_no 

is the current version number of this structure. (Input). It should be set to 
"rescurce_control_version_l". 

reserved_for 

specifies the User_id of the process for whom this reservation is made. (Input). 
The use of an asterisk (*) for a component name is permitted. If this element is 
blanks, the User_id of the current process is used. 
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reserved_by 

is the User_id of the process that is charged for this reservation (see "Notes" 
below). (Input). This element is ignored for an unprivileged reservation, and the 
current User_id is used. 

reservation_id 

is an identifier for this reservation group. (Input/Output). It is currently returned 
as an absolute clock time. 

n_items 

is the number of items being reserved. (Input) 

The rest of the items in this structure are currently ignored and should be set to 
zero. 

ACCESS REQUIRED 

Execute access to the rcp_sys_ gate is necessary to perform a privileged reservation. 
NOTES 

If system = "l"b, reservation_description ; reserved_by is used to specify the User_id of 
the process to be charged for this reservation. 

The reservation_description structure is strongly dependent on the resource_descriptions 
structure; that is, for each resource described in resource_descriptions, there must be a 
corresponding entry of the same index in reservation_description. 



Name: resource info 

The resource_info_ subroutine returns selected information about RCP resource types 
defined on the system. 

See the Programmer's Reference Manual for a description of the Multics resource 
control facility. 



Entry: resource__inf o $canonicalize_name 

This entry point applies the proper canonicalization to a resource name of a a given 
resource type. Each resource type can have a canonicalization routine, defined by the 
System Administrator in the Resource Type Master File (RTMF). This routine puts a 
resource name into standard form by stripping leading zeros, truncating overlong 
names, or applying other site-defined conventions. 
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USAGE 

declare resource_info_$canonical ize_name entry (char (*) , char (>'«) , 
char (*) , fixed bin (35)) ; 

call resource_i nf o_$canoni cal i ze__name (resource_type, resource_name, 
canon i ca 1 i zed_name , code) ; 

ARGUMENTS 

resource_type 

is the name of a defined resource type. (Input) 

resource_name 

is the string to be canonicalized. (Input) 

canonicalized_name 

is the canonicalized representation of resource_name. (Output) 

code 

is a standard status code. (Output) 



Entry: resource info Sdefaults 

This entry point fills a resource_descriptions structure with the default registration 
parameters defined in the RTDT. 

USAGE 

del resource_i nf o_$def aul ts entry (char (*) , char (>'«) , pointer, fixed bin 
fixed bin(35)) ; 

call resource_i nf o_$def aul ts (name, subtype, resource_desc_ptr , 
resource_no, code) ; 

ARGUMENTS 

name 

is the name of a defined resource type. (Input) 
subtype 

is the name of a subtype of the resource type, defined in the RTDT. (Input). If 

subtype is the null string, the master defaults for the resource type are used. 

resource_desc_ptr 

is the pointer to the entire resource_descriptions structure. (Input) 

resource_no 

specifies the resource description structure as defined by resource_descriptions item 
(resource_no). If resource_no is 0, all items are used. (Input) 
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code 

is a standard status code. (Output) 



Entry: resource info $get_type 

Given the name of a resource type, this entry point indicates whether the resource 
type named is a device or a volume. 

USAGE 

declare resource_i nf o_$get_type entry (char (*) , bit (1), fixed 
bin(35)); 

call resource_i nf o_$get_type (name, is_volume, code); 

ARGUMENTS 

name 

is the name of a defined resource type (see "Notes" below). (Input) 

iS_VOlumc 

is "l"b if the resource type given specifies a class of volumes. (Output). If M 0"b, 
the resource type given specifies a class of devices. 

code 

is a standard status code. (Output) 
NOTES 

A list of defined resource types can be obtained via the list_resource_types command. 



Entry: resource_info Slimits 

This entry point returns information about quantity and time limits for a given 
resource type. 

USAGE 

declare resource_i nfo_$ 1 imi ts entry (char (*) , fixed bin, fixed bin, 
fixed bin, fixed bin(35))» 

call resource_J nf o_$ 1 imi ts (name, max_quant i ty , def aul t_t ime, max_time, 
code) ; 

ARGUMENTS 

name 

is the name of a defined resource type. (Input) 
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max_quantity 

is the maximum number of this type of resource that a process can assign at one 
time. (Output) 

default_time 

is the default reservation time, in minutes, for this type of resource. (Output) 
max_time 

is the maximum allowed reservation time, in minutes, for this type of resource. 
(Output) 

code 

is a standard status code. (Output) 
NOTES 

The information returned by this entry point is from the Resource Type Description 
Table (RTDT). These are not the limits currently enforced by RCP. 



Entry: resource info Slock on release 

This entry point returns a value specifying whether resources of a given type are to 
be locked for manual clearing at release time. 

USAGE 

del resource_i nf o__$ lock on__release entry (char (*) , bit(l) aligned, 
fixed bin (35)) ; 

call resource_i nf o_$ lock_on_rel ease (name, lock__sw, code); 

ARGUMENTS 

name 

is the name of a defined resource type. (Input) 
lock_sw 

specifies whether the resource is locked at release time. (Output) 

"l"b lock the resource 

"0"b do not lock the resource 

code 

is a standard status code. (Output) 
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Entry: resource info Smates 

This entry provides information about the resource type(s) with which the given 
resource type can be mounted. 

USAGE 

declare resource_i nf o_$mates entry (char (*) , fixed bin, char (*) 
dimension (*) % fixed bin (35) ) ; 

call resource_i nf o__$mates (name, n_mates, mates, code); 

ARGUMENTS 

name 

is the name of a defined resource type. (Input) 
n_mates 

is the number of mates returned. (Output) 
mates 

contains the name(s) of the resource type(s) that can may be mounted with this 
resource (see "Notes" below). (Output) 

code 

is a standard status code. (Output) 
NOTES 

If the number of elements in mates is too small to hold all the mates for the given 
resource type, code is set to error_table_$smallarg, and mates is set to the null string. 
However, n_mates still contains the number of mates associated with the given 
resource type. 
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Name: reversion 

This procedure causes the handler currently established for the given condition in the 
calling block activation to be disestablished. If no handler for the given condition is 
established in the calling block activation, no action is taken. A description of the 
condition mechanism is given in the Multics Programmer's Reference manual in the 
entitled "The Multics Condition Mechanism". 

USAGE 

declare reversion_ entry (char(*)); 
call reversion_ (name); 
ARGUMENTS 
name 

is the name of the condition for which the handler is to be disestablished. 
(Input) 

NOTES 

The condition name unclaimed_signal is an obsolete special condition name and should 
not be used. 

A call to reversion, must be used only to revert a handler established by a call to 
condition., reversion, must not be used to revert a handler established by a PL/ 1 on 
statement. 

In a PL/ 1 program, when a call to reversion, appears within the scope of a begin 
block or internal procedure of a procedure, the no.quick.blocks option must be 
specified in the procedure statement of that procedure. The no.quick.blocks option is 
a nonstandard feature of the Multics PL/ 1 language and, therefore, programs using it 
may not be transferable to other systems. 
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Name: ringO get 

The ringO_get_ subroutine returns the name and pointer information about hardcore 
segments. 



Entry: ringO get_$definition 

This entry point is used to ascertain the offset of a symbol in a hardcore segment in 
the running Multics supervisor. 

USAGE 

declare r i ngO_get_$def i ni t ion entry (ptr, char (*) , char (*) , 
fixed bin (18), fixed bin, fixed bin (35)); 

call r i ngO_get_$def ini tion (seg_ptr, component_name, sym_name, offset, 
type, code) ; 

ARGUMENTS 

seg_ptr 

is a pointer to the base of the segment in which it is desired to obtain a symbol 
offset. (Input/ Output). If supplied as null, the segment that bears the name 
component_name in the SLT is used, and seg_ptr is returned as output as a 
pointer to the base of this segment. 

component_name 

is the name of the segment or segment bound component in which the symbol, 
sym_name, is to be found. (Input). If sym_name is an unambiguous reference in 
the segment defined by seg_ptr, this parameter can be given as a null string. If 
seg_ptr is given as null, this parameter must be supplied, and specifies the 
segment name as well. 

sym_name 

is the name of the external symbol in the segment specified by seg_ptr or 
component_name. (Input). If more than one external symbol of this name appears 
in this segment, component_name is used to select the correct component. 

offset 

is the offset of this definition, if found, into the section of the specified segment 
as specified by type. (Output) 

type 

is the definition type of this definition, detailing in which section of the specified 
segment this definition resides. (Output) 

code 

is a standard status code. (Output). If the the segment specified has no 
definitions, error_table_$no_defs is returned. 
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Entry: ringO get Sdefinition given sit 

This entry point is used to ascertain the offset of a symbol in a hardcore segment in 
other than the running Multics supervisor. Copies of the Segment Loading Table 
(SLT), SLT name table, and hardcore definitions segment are supplied. 

USAGE 

declare r i ngO_get_$def ini t i on_g i ven_s 1 1 entry (ptr, char (*) , char (*) , 
fixed bi n (18) • fixed bin, fixed bin(35), ptr, ptr, ptr); 

call r i ngO_get_$def i ni t ion_g i ven_s 1 t (seg_ptr, component_name, sym_name, 
offset, type, code, slt_ptr, nametbl_ptr , def tbl_ptr) : 

ARGUMENTS 

seg_ptr 

is a pointer to the base of the segment in which it is desired to obtain a symbol 
offset (Input/ Output). If supplied as null, the segment that bears the name 
componeni_name in the SLT is used, and seg_ptr is returned as output as a 
pointer to the base of this segment. 

component_name 

is the name of the segment or segment bound component in which the symbol, 
sym_name, is to be found. (Input). If sym_name is an unambiguous reference in 
the segment defined by seg_ptr, this parameter can be given as a null string. If 
seg_ptr is given as null, this parameter must be supplied, and specifies the 
segment name as well. 

sym_name 

is the name of the external symbol in the segment specified by seg_ptr or 
component_name. (Input). If more than one external symbol of this name appears 
in this segment, component_name is used to select the correct component. 

offset 

is the offset of this definition, if found, into the section of the specified segment 
as specified by type. (Output) 

type 

is the definition type of this definition, detailing in which section of the specified 
segment this definition resides. (Output) 

code 

is a standard status code. (Output). If the the segment specified has no 
definitions, error_table_$no_defs is returned. 

slt_ptr 

is a pointer to the copy of the segment loading table (SLT) to be used. (Input). 
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nametbl_ptr 

is a pointer to the corresponding copy of the SLT name table. (Input) 
deftbl_ptr 

is a pointer to the corresponding copy of the hardcore definitions segment 
(definitions,.). (Input) 



Entry: ringO__get Sname 

This entry point returns the primary name and directory name of a ring 0 segment 
when given a pointer to the segment 

USAGE 

declare r i ngO_get_$name entry (char (*) , char (*) , ptr, fixed bin); 
call r i ngO_get_$name (dir_name, entryname, seg_ptr, code); 
ARGUMENTS 
dir_name 

is the pathname of the directory of the segment (Output). If the segment does 
not have a pathname (as is the case for most hardcore segments), this is returned 
as a null string. 

entryname 

is the primary name of the segment (Output) 
seg_ptr 

is a pointer to the ring 0 segment (Input) 

code 

is a standard status code. (Output). It is nonzero if, and only if, seg_ptr does 
not point to a ring 0 segment. 



Entry: ringO get $name__given sit 

This entry point is analogous to the name entry point except that external SLT and 
name tables are used, instead of the versions of these tables currently being used by 

LUC dJdLClll. 

USAGE 

declare r i ngO_get_$name_given_sl t entry (char (*) , char (*) , ptr, fixed 
bin) ; 

call r i ngO_get_$name_g i ven_sl t (dir_name, entryname, seg_ptr, code, 
si tp, namep) ; 
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ARGUMENTS 
dir_name 

is the pathname of the directory of the segment. (Output). If the segment does 
not have a pathname (as is the case for most hardcore segments), this is returned 
as a null string. 

entryname 

is the primary name of the segment. (Output) 
seg_ptr 

is a pointer to the ring 0 segment. (Input) 

code 

is a standard status code. (Output). It is nonzero if, and only if, seg_ptr does 
not point to a ring 0 segment. 

sltp 

is a pointer to an SLT that contains information about the segment. (Input) 
namep 

is a pointer to a name table (associated with the above SLT) containing the names 
of segments. (Input) 



Entry: ringO get__$names 

This entry point returns all the names and the directory name of a ring 0 segment 
when given a pointer to the segment. 

USAGE 

declare r i ngO_get_$ names entry (char (*) , ptr, ptr, fixed bin); 
call r i ngO_get_$names (dir_name, names_ptr, seg_ptr, code); 
ARGUMENTS 
dir_name 

is the pathname of the directory of the segment. (Output) 
names_ptr 

is a pointer to a structure (described in "Notes" below) containing the names of 
the segment. (Output) 

seg_ptr 

is a pointer to the ring 0 segment. (Input) 

code 

is nonzero if, and only if, seg_ptr does not point to a ring 0 segment. (Output) 
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NOTES 



The following structure is used: 



del 1 segnames 
2 count 
2 names 



based (namesptr) aligned, 
fixed bin, 

(50 refer (segnames .count) ) , 



3 length 
3 name 



fixed bin, 
char (32) ; 



STRUCTURE ELEMENTS 
count 

is the number of names, 
names 

is a substructure containing an array of segment names, 
length 

is the length of the name in characters, 
name 

is the space for the name. 



Entry: ringO get Ssegptr 

This entry point returns a pointer to a specified ring 0 segment. Only the name is 
used to determine the pointer. 



declare r i ngO_get_$segptr entry (char (*) , char (*) , ptr, fixed bin (35)); 

call r i ngO_get_$segptr (dir_name, entryname, seg_ptr, code); 

ARGUMENTS 

dir_name 

is ignored. (Input) 

entryname 

is the name of the ring 0 segment for which a pointer is desired. (Input) 
seg_ptr 

is a pointer to the segment. (Output) 



is a standard status code. (Output). It is nonzero if, and only if, the entry is not 



USAGE 



code 



found. 
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NOTES 

If the entry is not found, seg_ptr is returned as a null pointer. 



Entry: ringO get Ssegptr given sit 

This entry point is analogous to the segptr entry point except that external SLT name 
tables are used, instead of the versions of these tables currently being used by the 
system. 

USAGE 

declare r i ngO_get_$segptr_g i ven_s 1 1 entry (char (*) , char (*) , ptr, 
fixed bin(35)» ptr, ptr); 

call r i ngO_get_$segptr_g i ven_s 1 1 (dir_name, entryname, seg_ptr, code, 
s 1 tp, namep) ; 

ARGUME NTS 

dir_name 

is ignored. (Input) 

entryname 

is the name of the ring 0 segment for which a pointer is desired. (Input) 
seg_ptr 

is a pointer to the segment. (Output) 

code 

is a standard status code. (Output). It is nonzero if, and only if, the entry is not 
found. 

sltp 

is a pointer to an SLT that contains information about the segment (Input) 
namep 

is a pointer to a name table (associated with the above SLT) containing the names 
of segments. (Input) 
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Name: ring__zero peek 

The ring_zero_peek_ subroutine is used to copy information out of an inner ring 

segment. The user must have access to either the phcs_ gate or the 

metering_ring_zero_peek_ gate in order to use any of the entry points in this 
subroutine. The phcs_ gate allows unrestricted access to all inner ring segments; 

metering_ring_zero_peek_ allows the user to examine specifically those data bases that 

are useful for metering the system. The program chooses the appropriate gate 
depending on the user's access and the segments being examined. 

USAGE 

declare r i ng_zero_peek_ entry (ptr, ptr, fixed bin (19) » fixed bin (35)); 

call r i ng_zero_peek_ (ptrO, ptr_user, nwords, code); 

ARGUMENTS 

ptrO 

is a pointer to the data in ring 0 that is to be copied out. (Input) 
ptr_user 

is a pointer to the region in the user's address space where the data is to be 
copied. (Input) 

nwords 

is the number of words to be copied. (Input) 

code 

is the standard status code that is nonzero if the user did not have access to the 
requested data. (Output) 



Entry: ring zero peek $by definition 

This entry point is used to copy information out of a named segment in the Multics 
supervisor, starting at a named symbol. It is like ring L _zero_peek_$by_name, except 
that the copying is done from the specified definition, rather than from the base of 
the segment. 

USAGE 

del r i ng_zero_peek_$by_def i ni tion entry (char (*) , char (*) , 

fixed bin (18), pointer, fixed bin (19). fixed bin(35))» 

call r i ng_zero_peek_$by_def i ni tion (segment_name, symbol_name, offset, 
ptr_user, word_count, code); 
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ARGUMENTS 
segment_name 

is the name of the supervisor segment from which words are to be copied. 
(Input). It cannot be a pathname. 

symbol_name 

is the name of the external symbol in the specified segment at which copying is 
to start (Input) 

offset 

is the offset from the specified definition at which copying is to start. (Input). 
It can be specified as zero to cause copying to start at the specified definition. 

ptr_user 

is a pointer to the area in the outer ring where the data is to be copied. (Input) 
word_count 

is the number of words to be copied. (Input) 

code 

is a standard status code. (Output). It is nonzero if the segment cannot be 
found, if the specified external symbol does not exist or is ambiguous, or if the 
user does not have sufficient access to copy the requested data. 

NOTES 

See "Notes" to ring_zero_peek_$by_name entry point. 



Entry: ring zero peek $by name 

This entry point is used to copy information out of a named segment in the Multics 
supervisor. It is like ring_zero_peek_, except that the name of the ring zero segment 
is provided, rather than a pointer to it. 

USAGE 

del r i ng_zero_peek_$by_name entry (char (*) , fixed b i n (1 8) , pointer, 
fixed bin (19) , fixed bin (35)) ; 

call r i ng_zero_peek_$by_name (segment_name, offset, copy_ptr, 
word count, code) ; 
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ARGUMENTS 
segment_name 

is the name of the supervisor segment from which data is to be copied, It 
cannot be a pathname. (Input) 

offset 

is the offset from the beginning of the segment at which copying is to start 
(Input). It can be specified as zero to cause copying to start from the base of 
the segment. 

copy_ptr 

is a pointer to the area in the outer ring where the data is to be copied. (Input) 
word_count 

is the number of words to be copied. (Input) 

code 

is a standard status code. (Output). It is nonzero if the segment cannot be 
found, or if the user does not have sufficient access to copy the requested data 
from it. 

NOTES 

This entry point can be used to avoid a call to ringO_get_. For examining segments in 
the supervisor, this entry point and the by_definition entry point are recommended 
because they are much simpler to use than ringO_get_, and they are only minimally 
less efficient. Generally, it is nearly as efficient to use this entry point as it is to 
save static pointers to inner ring objects. 



Entry: ring zero peek $get max length 

This entry point is used to determine the maximum length of a named ring zero 
segment. 

USAGE 

del r i ng_zero_peek_$get_max_l ength entry (char (*) , fixed bin (19) » 
fixed bin (35)) ; 

call r i ng_zero_peek_$get_max_i ength (seg_name, max_length, code); 



2-695 



AG93-05 



ring_zero_peek_ 



ring_zero_peek_ 



ARGUMENTS 
seg_name 

is the name of the ring zero segment. (Input) 
max_length 

is the maximum length (in words) of the segment. (Output) 

code 

is a standard status code. (Output). It is nonzero if the user does not have 
sufficient access to copy the requested data, or if the segment does not exist. 



Entry: ring zero peek $get max_length ptr 

This entry point is used to determine the maximum length of a specified segment by 
examining its SDW. The user must have sufficient access to examine the SDW for the 
segment 

USAGE 

del r i ng_zero_peek_$get_max_l ength_ptr entry (pointer, fixed bin (19). 
fixed bin (35) ) 5 

call r i ng_zero_peek_$get_max_l ength_ptr (seg_ptr, max_length, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment for which the max length is to be returned. (Input). 
If the segment is not active at the time of the call, the user must have sufficient 
access to reference the segment, and this reference causes a segment fault. 

max_length 

is the maximum length (in words) of the segment (Output) 

code 

is a standard status code. (Output). It is nonzero if the user does not have 
sufficient access to copy the requested data, or if the segment does not exist. 
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Name: run 

The run_ subroutine manages the environment for a run unit and invokes the main 
program of a run unit. See the documentation of the run command in the Commands 
manual for an explanation of run units. This entry sets up the run unit environment, 
invokes the main program, and restores the environment when the run ends. 

USAGE 

declare run_ entry (entry, ptr, ptr, fixed bin (35)); 
call run_ (main_entry, argl i st__ptr , run_cs_ptr, code); 
ARGUMENTS 
main_entry 

is the entry point to be called as the main program of the run unit. (Input) 
arglist_ptr 

points to the argument list for the main program. (Input) 
run_cs_ptr 

(Input) points to the following structure which is declared in 
run_control_structure. incl. pll: 

del 1 run_control_structure aligned based (run_cs_ptr) , 
2 version fixed bin, 

2 flags al igned, 

3 ec bit(l) unaligned, 

3 pad bit (35) unaligned, 

2 ref erence_name_swi ten fixed bin, 
2 time_limit fixed bin (35) 5 

where: 
version 

is the version number of the structure. It should be set to 
run_control_structure_version_l. 

ec 

is "l"b if the main program is exec_com (main_entry must still be set), 
otherwise ec must be "0"b. 

pad 

must be "0"b. 



2-697 



AG93-05 



run 



ref erence_name_switch 

is set to one of the named constants NEW_REFERENCE_NAMES, 
COPY_REFERENCE_NAMES or OLD_REFERENCE_NAMES delcared in 
run_control_structure.incl.pl 1. 



is the interval in cpu seconds after which the program is to be interrupted. 

code 

is a standard status code. (Output) 
Entry: run Senvironment info 

This entry enables the symbolic debugging tools to obtain the saved stack header 
information used by a given stack frame. 



call run_$envi ronment_i nf o (stack_f rame_ptr , info_ptr, code); 

ARGUMENTS 

stack_frame_ptr 

points to an active stack frame on the current stack. (Input) 
info_ptr 

is a pointer to the env_ptrs structure defined in "Notes" below. 

code 

is a standard system status code. (Output) 



The info_ptr points to the following structure, declared in env_ptrs.inci.pii: 



time_limit 



USAGE 




NOTES 



del 1 env_ptrs 



al i gned based, 
fixed bin, 
fixed bin (35) , 



2 version 
2 pad 



2 lot_ptr 
2 isot_ptr 
2 clr_ptr 



ptr , 
ptr, 
ptr, 
ptr, 
ptr, 
ptr, 
ptr, 
ptr; 



2 combi ned_stat_ptr 

2 user_f ree_ptr 

2 sys_l i nk_i nf o_ptr 



2 rnt_ptr 
2 sct_ptr 
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STRUCTURE ELEMENTS 
version 

is the version number of this structure; it must be 1. 

pad 

is unused. 
lot_ptr 

points to the linkage offset table (LOT). 
isot_ptr 

points to the internal static offset table (ISOT). 
clr_ptr 

points to the area where linkage sections are allocated. 

combined_stat_ptr 

points to the area where separate static sections are allocated. 

user_free_ptr 

points to the area where user storage is allocated. 

sys_link_info_ptr 

points to the control structure for external static variables. 

rnt_ptr 

points to the reference name table. 
sct_ptr 

points to the static handler array. 



Name: runtime symbol__info 

This subroutine's various entry points return runtime information about program 
variables (address, type, etc.) for programs compiled with symbol tables (-table). 
Declarations for the entry points and the structures they return can be found in the 
include file runtime_symbol_info_.incl.pll. Most entry points take a pointer (symbol_ptr) 
to a symbol node, which can be obtained by calling stu_$find_runtime_symboi. Rather 
than return error codes, these entry points return null pointers or zero fields in their 
structures if the symbol node does not contain the requested information. Also see the 
various stu_ entry points for additional information about program variables and text 
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WARNING: 

these subroutines requires a good understanding of the symbol table structures 
generated by translators. For example, given a Pascal symbol "foo" declared 
variable of type packed array [1..10] of char, runtime_symbol_info_ does not 
return any useful information because this information resides in the symbol 
node for the TYPE of "foo". 



Entry: runtime sy mbol_inf o__$address 

This entry point returns information about the location of a symbol at runtime. 
USAGE 

declare runt i me_symbol_i nf o_$address entry (ptr, ptr, fixed bin (35)); 

call runt ime_symbol_i nf o_$address (symbol_ptr , info_ptr, code); 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 

info_ptr 

is a pointer to a user-allocated structure to be filled in by the call. This 
structure, called runtime_address_info, is described under "Notes" below. 

code 

is error_table_$unimplemented_version if run time_address_info. version has not been 
set to a valid version for the structure. 
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NOTES 



Information is returned in the following structure, declared in the include file 
runtime_symbol_inf o_.incl.pll: 



del 1 runt i me_address_i nf o 
2 version 
2 location 
2 class 
2 use_d i g i t 
2 units 

2 of f set_i s_encoded 
2 pad 
2 offset 



a 1 i gned based , 
char (8) , 
fixed bin 
f i xed b i n 
f i xed b i n 
fixed bin 
bit 
bit 



(18) unsigned unaligned, 
(6) unsigned unaligned, 

(1) unsigned unaligned, 

(2) unsigned unaligned, 
(1) unal igned, 
(8) unal i gned, 



fixed bin (35) ; 



STRUCTURE ELEMENTS 
version 

is the version of the structure, which 
RUNTIME_ADDRESS_INFO_VERSION_1. 



the caller must set to 



location 

is the offset of the data within the storage class specified by the next field. 

class 

is the storage class: 

0 No address information is available for this symbol. 

1-15 See the symbol table documentation in the Multics Reference Manual. 

use_digit 

is "l"b to indicate that units are digits if units = 3. 



36 bits 
1 bit 
9 bits 

18 / 4.5 bits 



units 

gives the unit of storage: 

0 word 

1 bit 

2 byte 

3 half-word /digit 

of f set_is_encoded 

is "l"b if the address is represented as an encoded offset in the next field. 

Encoded values, described in the symbol table documentation in the Reference 

Manual, are interpreted by stu_$decode_runtime_value_extended. 

offset 

is the offset of the start of the identifier with respect to the address specified by 
location and class. It is encoded if offset is encoded="l"b. 
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Entry: rimtime_symbol info $array 

This entry point returns information about array storage allocation. 
USAGE 

declare runt ime_symbol_i nfo_$ar ray entry (ptr, ptr, fixed bin (35)); 

call runt ime_symbol_i nf o_$array (symbol__ptr , info_ptr, code); 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 

info_ptr 

is a pointer to a user -allocated structure to be filled in by the call. This 
structure, called runtime_array_info, is described under "Notes" below. 



is error_table_$unimplemented_version if run time_array_info. version has not been 
set to a valid version for the structure. 

NOTES 

Information is returned in the following structure, declared in the include file 
runtime_symbol_inf o_.incl.pll: 

del 1 runt ime_array_i nf o aligned based, 

2 vers i on char (8) , 

2 access_info aligned, 

3 ndims fixed bin (6) unsigned unaligned, 

3 use_digit fixed bin (1) unsigned unaligned, 

3 array_units fixed bin (2) unsigned unaligned, 
3 vi rtual_or i gi n_i s_encoded 

bit (1) unal igned, 

3 pad bit (26) unaligned, 

2 vi rtual_or i gi n fixed bin (35). 

2 bounds (16) aligned, 



3 


f 1 ags 


al i gned, 




h 1 ower_i s_encoded 


bit (1) unal igned, 




k upper_i s_encoded 


bit (1) unal igned, 




k mul t i pi i er_i s_encoded 


bit (1) unal i gned, 




i+ pad 


bi t (33) unal i gned, 


3 


1 ower 


fixed bin (35) , 


3 


upper 


fixed bin (35) , 


3 


mul t i pi i er 


f i xed bin (35) , 


3 


subscr i pt_type 


fixed bin (35) , 


3 


subscr i pt_type_addr 


ptr; 
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STRUCTURE ELEMENTS 



version 

is the version of the structure, currently RUNTIME_ARRAY_INFO_VERSION_,l. 
ndims 

is the number of dimensions in the array (eg., 2 => N x M array). If this value 
is zero, the symbol node does not contain array information and the rest of the 
information in the structure is meaningless. 

use_digit 

is "l"b to indicate that units are digits if array_units = 3. 



array_units 

gives the unit of storage: 

0 word 36 bits 

1 bit 1 bit 

2 byte 9 bits 

3 half-word/digit 18 / 4.5 bits 



virtual_origin_is_encoded 

is "l"b if the origin is represented as an encoded value in the next field. 
Encoded values are interpreted by stu_$decode_runtime_value_extended. 

virtual_origin 

is the virtual origin of the array, in units given by array_units. Its value should 

be subtracted from the base address specified by the address location and class. 

This value is meaningless for Pascal conformant arrays, for which the origin is 
equal to low(l) * multiplier(l). 

bounds 

gives, for each dimension, information describing the bounds and subscript 



lower_is_encoded 

is "l"b if lower is an encoded value. 



upper_is_encoded 

is "l"b if upper is an encoded value. 

multiplier_is_encoded 

is "l"b if multiplier is an encoded value. 

lower 

is the lower bound of this dimension. 



upper 

is the upper bound of this dimension, 
multiplier 

is the size of an element in units given by array_units. 
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subscript_type 

for a Pascal array, this is the type of subscript allowed for this dimension. 
subscript_type_addr 

for a Pascal array, this is a pointer to a Pascal type node describing the type of 
subscript allowed for this dimension. It is null if there is no type node. 



Entry: runtime symbol_info Sarray dims 

This entry point returns the number of dimensions of an array. It returns null if the 
symbol has no dimensions. 

USAGE 

declare runt ime_symbol_i nf o_$array_d ims entry (pointer) returns (fixed 
bin); 

n_dims = runtime_symboi_info_$array_dims (symbo l_ptr) ; 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 



Entry: runtime symbol inf o Sbrother 

This entry point, given a pointer to a symbol node for an aggregate component, 
returns a pointer to the next component at the same level or null if this is the last 
component at this level of the aggregate. Given a pointer to a formal parameter, it 
returns a pointer to the node for the next parameter, or null if there is no next 
parameter. Given a pointer to any other symbol node whose level is <= 1 
(non_aggregate or top-level structure) and which has a name, returns a pointer to the 
next element on the list of symbol nodes ordered alphabetically by size. It returns 
null if there is no next symbol. 

USAGE 

declare runt ime_symbol_i nf o__$brother entry (pointer) returns (pointer); 

brother_ptr = runt ime_symbol_i nf o_$brother (symbo 1 _ptr) ; 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 
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Entry: runtime symbol info $father 

This entry point, given a pointer to a symbol node for an aggregate component, 
returns a pointer to the symbol node for its parent aggregate. Given a pointer to a 
symbol node whose level is <= 1 and which has a name, returns a pointer to the 
runtime block node that represents the block in which the identifier is declared. It 
returns null if father = 0 or if there is no father field. 

USAGE 

declare runt i me_symbol_i nf o_$f ather entry (pointer) returns (pointer); 

father_ptr = runt ime_symbol_i nfo_$f ather (symbol_ptr) ; 

ARGUMENTS 

symbol_ptr 

is a pointer to to a symbol node. (Input) 



Entry: runtime symbol info $f ather type 

This entry point, given a pointer to a symbol node for a Pascal enumerated type 
element, returns a pointer to the symbol node for the parent type. Otherwise, it 
returns null. 

USAGE 

declare runt i me_symbol_i nf o_$f ather_type entry (pointer) returns 
(poi nter) ; 

f ather_type_ptr = runt ime_symbol_i nfo_$f ather_type (symbol_ptr) ; 
ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 



Entry: runtime symbol info $level 

This entry point, given a pointer to a symbol node for an aggregate component, 
returns the level number of the component in the aggregate or zero if the symbol is 
not an aggregate component. Fields in a Pascal "with" block are at level 0. 

USAGE 

declare runt ime_symbol_i nf o_$ 1 evel entry (pointer) returns (fixed bin); 
1 eve l_number = runt ime__symbol_i nf o_$ I evel (symbol_ptr) ; 
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ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 

Entry: runtime symbol inf o $n variants 

This entry point, given a pointer to a symbol node for a tag field in a Pascal record, 
returns the number of case variants for the field. It returns 0 if the symbol is not a 
tag field. 

USAGE 

declare runt ime_symbol_i nfo_$n_var i ants entry (pointer) returns (fixed 
bin) ; 

n_variants - runt ime_symbol_i nfo_$n_var i ants (symbol_ptr) ; 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 

Entry: runtime symbol info Sname 

This entry point, given a pointer to a symbol node, returns a pointer to the symbol's 
name in packed form (see "Notes" below). It returns null if there is no name. 

USAGE 

declare runt ime_symbol_i nf o_$name entry (pointer) returns (pointer); 

name_string = runt i me_symbol_i nfo_$ name (symbol_ptr) -> acc. string; 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 

NOTES 

The variable acc.string is declared in the include file acc.incl.pll: 

del 1 acc based aligned, 

2 num_chars fixed bin (9) unsigned unaligned, 

2 string char (0 refer (acc . num_chars) ) unaligned; 
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Entry: runtime symbol info Snext 

This entry point, given a pointer to a symbol node, returns a pointer to the symbol 
node for the next identifier having the same name as the current identifier. It returns 
null if there is no name or if there are no more identifiers with the same name. 

USAGE 

declare runt i me_symbol_i nf o_$next entry (pointer) returns (pointer); 

next_symbol_ptr = runt ime_symbol_i nfo_$next (symbol_ptr) ; 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 



Entry: runtime symbol info $son 

This entry point, given a pointer to a symbol node for an aggregate, returns a pointer 
to the symbol node for the aggregate's first component. Given a pointer to a symbol 
node for a procedure, it returns a pointer to the symbol node for the first formal 
parameter. Given a pointer to a symbol node for an enumerated type, it returns a 
pointer to the symbol node for the first element of the type. Otherwise, it returns 
null. 

USAGE 

declare runtime_symbol_i nfo_$son entry (pointer) returns (pointer); 

son_ptr = runt ime_symbol_i nf o_$son (symbol_ptr) ; 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 
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Entry: runtime_symbol_inf o_$successor 

This entry point, given a pointer to a symbol node for a Pascal enumerated type 
element, returns a pointer to the symbol node for the next element in the set of 
enumerated values for the type, or null if there is no next element or no successor 
field. 

USAGE 

declare runt ime_symbol_i nf o_$successor entry (pointer) returns 
(poi nter) ; 

successor_ptr = runt ime_symbol_i nf o_$successor (symbol_ptr) ; 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 



Entry: runtime symbol info $type 

This entry point returns information about the data type of a symbol. 
USAGE 

declare runt ime_symbol_i nf o_$type entry (pointer, pointer); 

call runt ime_symbol_i nf o_$type (symbol_ptr, info_ptr); 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 

info_ptr 

is a pointer to a user-allocated structure to be filled in by the call This 
structure, called runtime_type_info, is described under "Notes" below. 
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NOTES 



Information is returned in the following structure, declared in the include file 
runtime_symbol_inf o_.incl.pll: 

del 1 runt ime_type_i nfo aligned based, 

2 vers i on char (8) , 
2 flags, 

3 aligned bit (1) unaligned, 

3 packed bit (1) unaligned, 

3 s i 2e_i s_encoded bit (1) unaligned, 

3 pad bit (25) unaligned, 
2 scale fixed bin (7) unaligned, 

2 (type, base_type) fixed bin (18) unsigned unaligned, 

2 (type_addr, base_type_addr) 

ptr , 

2 size fixed bin (35) ; 



STRUCTURE ELEMENTS 



version 

is the version of the structure, which the caller must set to 
RUNTIME_TYPE_INF0_VERSI0N_1. 

aligned 

is 'T'b if the value is aligned. The meaning of alignment depends on the type. 
Refer to the Reference Manual's section on the runtime symbol table. 

packed 

is 'T'b if the value is packed. Refer to the Reference Manual. 
size_is_encoded 

is 'T'b if size is represented as an encoded value. Encoded values are interpreted 
by stu_$decode_runtime_value_extended. 

scale 

is the scale factor for arithmetic values. Refer to the Reference Manual. 



type 

is the type of the symbol. The defined types are declared in the include file 
std_descriptor_types.incl.pll. 

base_type 

when not equal to 0, is used in Pascal type description nodes in the following 
cases: For subranges, it is either integer, Pascal char, or Pascal enumerated type 
instance. For arrays, sets, and record files, it is the type of the elements. For 
typed pointers, it is the type of the referenced variable. For function procedure 
types, it is the type of the return value. For other procedure types, it is null. 
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type_addr 

for Pascal user-defined and enumerated type variables, constants, record fields, 
procedure types, subscript types and base types, this is a pointer to a symbol 
node for the type that the symbol belongs to. Otherwise, it is null. 

base_type_addr 

is a pointer to a symbol node describing base_type, when base_type itself is 
neither 0 nor a simple type. Otherwise, it is null. 

size 

is the arithmetic precision, string size, or area size of the value. Refer to the 
Reference Manual. 



Entry: runtime symbol info $variant 

This entry point, given a pointer to a symbol node for a Pascal record field with case 
variants, returns information describing the variants. If the symbol is not a Pascal 
symbol, number_of_variants is returned as 0 and the rest of the information is invalid. 

USAGE 

declare runt ime_symbol_i nfo_$var i ant entry (ptr, ptr, fixed bin (35) ) J 

call runt irne_symbol_i nfo_$var i ant (symbol_ptr, info_ptr, code); 

ARGUMENTS 

symbol_ptr 

is a pointer to a symbol node. (Input) 

info_ptr 

is a pointer to a user-allocated structure to be fille din by the call. This 
structure, called runtime_variant_info, is described under "Notes" below. 

code 

is error_table_$unimpiemented_version if run time_variant_info. version has not been 
set to a valid version for the structure. 
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NOTES 

Information is returned in the following structure, declared in the include file 
runtime_symbol_inf o_.incl.pll: 

del 1 runtime_var iant_i nfo aligned based, 

2 version char (8) , 

2 number_of_var i ants fixed bin, 

2 f i rst_value_i n_set fixed bin (35), 

2 case (n_var i ants) , 

3 set_addr ptr, 

3 brother_addr ptr; 

STRUCTURE ELEMENTS 
version 

is the version of the structure, which the caller must set to 
RUNTIME_VARIANT_INFO_VERSION_l. 

number_of .variants 

is the number of variants if the symbol node is for a Pascal record tag field. 
Otherwise, it is null. 

first_value_in_set 

is the lowest value used to select a variant. 

case 

contains information for a particular variant. 
set_addr 

is a pointer to a bit string that specifies the cases of the variant. The bit string 
represents a set (one bit per set element) whose base type is the type of the 
symbol node pointed to by symbol_ptr. The first bit corresponds to first_value_in_set. 

brother_addr 

is a pointer to the first field of the variant part. 
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Name: set manager 

The sct_manager_ subroutine manipulates the System Condition Table (SCT), which is 
used to provide static handlers for certain conditions. It has entries to set a handler, 
get a pointer to a handler, and call a handler if one exists. 



Entry: set manager___$call__handler 

This entry point calls a handler if it exists. If none exists, the "continue" bit is set 
on to pass this information to the caller. 

USAGE 

declare sct_manager_$cal l_handler entry (ptr, char (*) , ptr, ptr, bit (1) 
al i gned) ; 

call sct_manager_$cal l_handler (mcptr, cname, nullQ, nul 1 () , continue); 

ARGUMENTS 

mcptr 

is a pointer to the machine conditions for the condition to be handled. The fault 
code within the scu data determines the handler to use. (Input) 

cname 

is the name of the condition being signalled. It is passed to the condition 
handler, if there is one. (Input) 

continue 

is set to "l"b if there is no handler, otherwise it is set by the handler. (Output) 

The third and fourth arguments are ignored; they must be null. They are declared 
for compatibility with the standard condition handler mechanism. 



Entry: set manager $get 

This entry point returns a pointer to the handler for the given index, or null if it 
does not exist 

USAGE 

declare sct_manager_$get entry (fixed bin, ptr, fixed bin (35)); 
call sct_manager_$get (fcode, hptr, code); 
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ARGUMENTS 
fcode 

is a fixed binary index into the SCT table. Appropriate values can be selected 
from static_handlers.incl.pll, which gives symbolic names for all indices currently 
defined. (Input) 

hptr 

is a pointer to the static handler, if it exists. (Output) 

code 

is a standard status code. (Output) 



Entry: set manager $set 

This entry point sets the handler for the given index to the one given in the call. 
USAGE 

declare sct_manager_$set entry (fixed bin, ptr, fixed bin (35)); 

call sct_manager_$set (fcode, hptr, code); 

ARGUMENTS 

fcode 

is a fixed binary index into the SCT table. Appropriate values can be selected 
from static_handlers.incl.pll, which gives symbolic names for all indices currently 
defined. (Input) 

hptr 

is a pointer to the static handler, if it exists. (Input) 

code 

is a standard status code. (Output) 
NOTES 

The System Condition Table is a based array of 127 packed pointers, pointed to by 
the sct_pointer in the stack_header of the stack for the ring in which sct_manager_ is 
executing. The pointers point to the entry to call, and a null value is used for the 
environment portion of the entry. A static handler has the same calling sequence as 
any other condition handler. SCT indices are assigned by hardcore systems programmers. 
Since sct_manager_$call_handler uses machine conditions to locate the handler, 
conditions without machine conditions (e.g., software conditions such as PL/I support) 
cannot have static handlers. Ring 0, rather than the user, ensures that there is a 
proper fault code in the conditions. 
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Name: search paths 



Entry: search paths $find dir 

The search_paths_$find_dir entry point, when given a search list and an entry name, 
returns the absolute pathname of a directory in which the entry name can be found. 
The directories in the search list are searched in order for the entry name. 

USAGE 

declare search_paths_$f i nd_d i r entry (char (*) , ptr, char (*) , char (*) , 
char (*) , fixed binary (35)); 

call search_paths_$f i nd_d i r (sl_name, search_seg_ptr , entryname, 
ref_path, dir_name, code); 

ARGUMENTS 

sl_name 

is the search list name. (Input) 
search_seg_ptr 

is a pointer to the search segment If this pointer is null, then the process search 
segment is used. (Input) 

entryname 

is the entryname to search for. (Input) 
ref_path 

is the directory name used for the "-referencing_dir" search path. If ref_path is 
null, then the "-referencing_dir" search path is skipped. (Input) 

dir_name 

is the directory in which the entryname was found. (Output) 

code 

is a standard status code. (Output) It can be one of the following: 

error_table_$no_search_list 

the search list was not in the search segment. 

error_table_$noentry 

the entryname was not found in a directory in the search list. 
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Entry: search__paths__$find__all 

The search_paths_$find_all entry point, when given a search list and an entry name, 
returns the absolute pathnames of directories in which the entry name can be found. 
The directories in the search list are searched in order for the entry name. 

USAGE 

declare search_paths_$f i nd_al 1 entry (char (*) , ptr, char (*) , char (*) , 
ptr, fixed binary, ptr, fixed binary(35)); 

call search_paths_$f i nd_al 1 (sl_name, search_seg_ptr , entryname, 

ref_path, s l_i nf o_area_ptr , s l_i nf o_vers i on, sl_info_ptr, code); 

ARGUMENTS 
sl_name 

is the search list name. (Input) 
search_seg_ptr 

is a pointer to the search segment. If this pointer is null, then the process search 
segment is used. (Input) 

entryname 

is the entry name to search for. (Input) 
ref_path 

is the directory name used for the "-ref erencing_dir" search path. If ref_path is 
null, then the "-referencing_dir" search path is skipped. (Input) 

sl_info_area_ptr 

is a pointer to an area in which sl_info can be allocated. (Input) 

sl_info_version 

is the version of the sl_info structure required. (Input) 

sl_info_ptr 

is a pointer to the sl_info structure containing the directories which contain the 
entry name. (See search_paths_$get). (Output) 

code 

is a standard status code. (Output) It can be one of the following: 

error_table_$no_search_list 

the search list was not in the search segment. 

error_table_$noentry 

the entryname was not found in a directory in the search list 
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Entry: search paths $get 

The search_paths_$get entry point returns the search paths in a search list. 
USAGE 

declare search_paths_$get entry (char (*) , bit (36), char (*) , ptr, ptr, 
fixed binary, ptr, fixed binary (35)); 

call search_paths_$get (sl_name, s1_control, ref_path, search_seg_ptr , 
s l_i nf o_area_ptr , s l_i nf o_vers i on, sl_info_ptr, code); 

ARGUMENTS 

sl_name 

is the search list name. (Input) 
sl_control 

is an expansion control mask. See the sl_control_s structure in "Notes" below. 
(Input) 

ref_path 

is the directory name used for the "-referencing_dir" search path. If ref_path is 
null, then the "-referencing_dir" search path is skipped. (Input) 

search_seg_ptr 

is a pointer to the search segment. If this pointer is null, then the process search 
segment is used. (Input) 

sl_info_area_ptr 

is a pointer to an area in which sl_info can be allocated. (Input) 

sl_info_version 

is the version of the sl_info structure required. (Input) 

sl_info_ptr 

is a pointer to the sl_info structure containing the search paths in the search list. 
(Output) (See "Notes" below). 

code 

is a standard status code. (Output) It can be the following: 

error_table_$no_search_list 

the search list was not in the search segment. 
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NOTES 

The sl_control argument is defined by the sl_control_s structure contained in 
sl_control_s.incl.pll. Expanding the "-referencing_dir" keyword substitutes the ref_path 
argument for the keyword. 

del 1 sl_info 

2 version 
2 num_paths 
2 change_i ndex_p 
2 change_index 
2 padl 
2 paths 

3 type 

3 code 

3 pad2 

3 pathname 

STRUCTURE ELEMENTS 

version 

is the version of the sl_info structure (sl_info_version_l) which is also declared in 
the include file. 

num_paths 

is the number of search paths in this structure. 
change_index_p 

is a pointer to the search lists' update count. The update count is a fixed binary 
(71) integer, and is incremented each time the search list is modified. The caller 
can determine if the search list has been modified by comparing change_index in 
this structure with the value pointed to by change_index_p. 

change_index 

is the current value of the search lists' update count. 

padl 

is unused, 
path, type 

specifies the type of the search path. Keywords in sl_info.inel.pll define the 
possible values. 

path, code 

is a standard status code for this search path. 



aligned based (s l__i nf o_p) , 
fixed binary, 
fixed binary, 
poi nter , 

f i xed bi nary (71) , 
(6) bit (36), 
(sl_info_num_paths refer 

(sl_i nfo.num_paths) ) , 
fixed binary, 
f i xed bi nary (35) » 
bit (36) , 

char (168) unaligned; 
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path.pad2 

is unused. 

path, pathname 

is the search path. 



Entry: search paths $set 

The search_paths_$set entry point sets the search paths of a search list. 
USAGE 

declare search_paths_$set entry (char (*) , ptr, ptr, fixed binary (35)) 5 
call search_paths_$set (sl_name, search_seg_ptr , sl_info_ptr, code); 
ARGUMENTS 
sl_name 

is the search list name. (Input) 
search_seg_ptr 

is a pointer to the search segment. If this pointer is null, then the process search 
segment is used. (Input) 

sl_info_ptr 

is a pointer to an sl_info structure (see search_paths_$get) containing the search 
paths for the search list. If null, then the search list is set to its default. (Input) 

code 

is a standard status code. (Output) It can be one of the following: 

error_tabie_$action_not_performed 

the search list was not changed. (See "Notes" below). 

error_table_$new_search_list 

a new search list was created. This is only a warning. 

error_table_$no_search_list_default 
the search list has no default. 

NOTES 

If the error_table_$action_not_performed status code is returned, then some search 
path may be invalid. A non-zero code for a search path in the sl_info structure 
indicates that the search path was invalid. 
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Entry: search paths Slist 

The search_paths_$list entry point returns a linked list of the search list names that 
are in a search segment. 



declare search_paths_$ 1 i st entry (ptr, ptr, fixed binary, ptr, 
fixed binary (35)) ; 

call search_paths_$ 1 i st (search__seg_ptr , s 1_1 i st_area_ptr , 
sl_l ist_version, sl_list_ptr, code); 

ARGUMENTS 

search_seg_ptr 

is a pointer to the search segment. If this pointer is null, then the process search 
segment is used. (Input) 

sl_list_area_ptr 

is a pointer to an area in which a linked list of sl_list structures can be 
allocated. (Input) 

sl_list_version 

is the version of the sl_list structure required. (Input) 



is a pointer to a linked list of sl_list structures containing the names of the 
search lists in the search segment (Output) (See "Notes" below). 



USAGE 



sl_list_ptr 



code 



is a standard status code. (Output) 



NOTES 



The sl_list structure is contained in the include file sl_list.incl.pll: 



del 1 si list 



based, 

fixed binary, 
poi nter , 
f i xed bi nary , 
(3) bit (36) , 

(s 11 i st_name_count refer (si 1 i st.name_count) ) 

char (32); 



2 version 

2 1 ink 

2 name_count 

2 pad 

2 names 
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ARGUMENTS 
version 

is the version of the sl_list structure (sl_list_version_2) which is also declared in 
the include file. 

link 

is a pointer to the next sljist structure in the linked list, or null if this is the 
last structure in the linked list 

name_count 

is the number of synonyms this search list has. 

pad 

must be 0. 
names 

is an array of the names of this search list 
Entry: search paths Sdelete list 

The search_paths_$delete_list entry point deletes a search list from a search segment. 
USAGE 

declare search_paths_$del ete_l i st entry (char (*) , ptr, fixed bin (35)); 
call search_paths_$del ete_l i st (sl_name, search_seg_ptr , code); 
ARGUMENTS 
sl_name 

is the search list name. (Input) 
search_seg_ptr 

is a pointer to the search segment. If this pointer is null, then the process search 
segment is used. (Input) 

code 

is a standard status code. (Output) It can be the following: 

error_table_$no_search_list 

the search list was not in the search segment. 
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Entry: search paths $init__search seg 

The seareh_paths_$init_search_seg entry point initializes a search segment 
USAGE 

declare search_paths_$ i ni t_search_seg entry (ptr, fixed bin(35))* 
call search__paths_$ i ni t_search__seg (search_seg_ptr , code); 
ARGUMENTS 
search_seg_ptr 

is a pointer to the search segment. If this pointer is null, then the process search 
segment is used. (Input) 

code 

is a standard status code. (Output) 



Name: send__as_request 

The send_as_request_ subroutine contains 
Answer Service Request server. 



entry points that send messages to the system 



Entry: send as request Sblock 

sends an as_request, and blocks to await the system's reply. 
USAGE 

declare send_as_request_$b1ock entry (ptr, fixed bin, bit (72) aligned, 
bit (72) aligned, f ixed bin (35) ) ; 

call send_as_request_$block (as_request_ptr , as_request_l en, 
as_request_id, as_request_repl y , code) ; 

ARGUMENTS 

as_request_ptr 

is a pointer to standard as_request structure. (Input) as_request_struetures begin 
with a header declared in as_request_header.incl.pll. Declarations for most as 
request info structures are found in as_requests.incl.pll. It is not recommended 
that any application code send as_requests. Subroutine interfaces are available for 
all the supported as_request facilities. 
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as_request_len 

is the length of the standard as_request structure, in words. (Input) 
as_request_id 

is the unique identifier assigned to the request. (Output) 
as_request_reply 

is the event message returned by the system in reply to the request (Output) 

code 

is a standard system status code. (Output) 



Entry: send as request $no block 

This entry point sends an as request message to the system as request server, and does 
not block to await a reply. 

USAGE 

declare send_as_request_$no_block entry (ptr, fixed bin, b i t (72) 
a 1 i gned s f ? xed b ? n (35) ) I 

call send_as_request_$no_block (as_request_ptr , as_request_l en, 
as_request_id, code) ; 

ARGUMENTS 

as_request_ptr 

is a pointer to standard as_request structure. (Input) as_request_structures begin 
with a header declared in as_request_header.incl.pll. Declarations for most as 
request info structures are found in as_requestincl.pll. It is not recommended 
that any application code send as_requests. Subroutine interfaces are available for 
all the supported as_request facilities. 

as_request_len 

is the length of the standard as_request structure, in words. (Input) 
as_request_id 

is the unique identifier assigned to the request. (Output) 

code 

is a standard system status code. (Output) 
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Name: send mail 

The send_mail_ subroutine sends an interactive message or mail to a specified user. 
USAGE 

declare send_mail_ entry (char (*) , char (*) , ptr, fixed bin(35))» 
call sendjnai1_ (destination, message, info_ptr, code); 
ARGUMENTS 
destination 

is a Person_id.Project_id destination. (Input) 
message 

is the text of the message to be sent. (Input) 
info_ptr 

points to the structure described in "Notes" below. (Input) 
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code 

is a standard status code. (Output) It can be one of the following: 
error_table_$noentry 

if the mailbox is not found. 
error_table_$no_append 

if the sending process has insufficient access to add a message. 
error_table_$wakeup_denied 

the sending process has insufficient access to send a wakeup. 
error_table_$messages_def erred 

if the recipient process is deferring messages. 
error_table_$messages_of f 

if the recipient is not logged in or the recipient process has not been 

initialized for receiving messages. 
error_table_$no_inf o 

if the sending process is not given any information because it has a lower 

AIM authorization than the recipient process. 



Entry: send mail $access class 

This entry is identical to send_mail_, except that the caller may specify the access 
class of the message. (In send_mail_, the access class of the message is always equal 
to the authorization of the calling process.) This entry is of use only if a site is 
using AIM. For information on access classes, see the Programmer's Reference Manual. 

USAGE 

declare send_ma i l_$access_c 1 ass entry (char (*) , char (*) , ptr, 
bit (72) aligned, fixed bin (35)); 

call send_ma i l_$access_c 1 ass (destination, message, info_ptr, 
access_c 1 ass , code); 

ARGUMENTS 

destination 

is a Person_id. Projected destination. (Input) 
message 

is the text of the message to be sent (Input) 
info_ptr 

points to the structure described in "Notes" below. (Input) 

access_class 

is the access class of the message. (Input) 

code 

is a standard status code. (Output) 
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Entry: send mail $path 

This entry point sends an interactive message or mail to a specified mailbox. 
USAGE 

declare sendjna i l_$path entry (char (*) , char (*) , char (*) , ptr, 
fixed bin (35)) ; 

call sendjnai l_$path (dir_name, entryname, message, info_ptr, code); 

ARGUMENTS 

dir_name 

is the directory name of a mailbox. (Input) 
entryname 

is the entryname of a mailbox. (Input) The .mbx suffix is added if it is not 
supplied. 

message 

is the text of the message to be sent. (Input) 
info_ptr 

points to the structure described in "Notes" below. (Input) 

code 

is a standard status code. (Output) 



Entry: send mail $path__access class 

This entry point sends a message to a specified mailbox, allowing the user to specify 
the access class of the message. 

USAGE 

declare sendjnai l_$path__access_c 1 ass entry (char (*) , char (*) , char (*) , 
ptr, b i t (72) aligned, fixed bin (35)); 

call sendjnai l_$path_access_c 1 ass (dir__name, entryname, message, 
info_ptr, access_class, code); 
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ARGUMENTS 
dir_name 

is the directory name of a mailbox. (Input) 
entryname 

is the entryname of a mailbox. (Input) The .mbx suffix is added if it is not 
supplied. 

message 

is the text of the message to be sent (Input) 
info_ptr 

points to the structure described in "Notes" below. (Input) 

access_class 

is the access class of the message. (Input) 

code 

is a standard status code. (Output) 
NOTES 

Normally the message is written into the mailbox of the receiver at the access_class 
specified by the sender. However, if send_mail_info.wakeup is "l"b and the receiver is 
accepting messages, and further, if the authorization of the receiver is greater than or 
equal to the access_class of the message, the access_class of the message is 
automatically upgraded to the authorization of the receiver. This allows the receiver to 
delete the message once he has read it. 

INFO STRUCTURE 

The info_ptr pointer points to the following structure (found in the include file, 
send_mail_inf o.incl.pll): 

del 1 send_mai l_i nf o aligned, 

2 version fixed bin, 

2 sent_from char (32) aligned, 

2 switches, 



3 wakeup 


b' 


t(D 


unal , 


3 mbzl 


b 


t(D 


unal , 


3 always_add 




t(l) 


i ma 1 
una i » 


3 never_add 


b 


t(D 


unal , 


3 notify 


b 


t(l) 


unal , 


3 acknowledge 


b 


t(l) 


unal , 


3 mbz 


b 


t(30) 


unal ; 
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STRUCTURE ELEMENTS 
version 

identifies the version of the structure being used. Currently this number must be 
2. 

sent_from 

gives additional information about the sender, e.g., name of anonymous user or 
name of network site. 

wakeup 

indicates whether a wakeup is sent with the message. 
'T'b yes 
"0"b no 

always_add 

indicates whether the message is to be added even if a wakeup could not be sent. 
'T'b yes 
"0"b no 

never_add 

tests whether a wakeup can be sent, without trying to add a message. 
'T'b yes 
"0"b no 

notify 

indicates that this message is a mail notification. After sending a piece of mail, a 
second message should be sent which has the bit ON so that the receiving process 
(if any) will print the "You have mail." notification. 
'T'b this is a mail notification 

"0"b this is NOT a mail notification, but either mail or an interactive message 
depending on the "wakeup" bit above. 

acknowledge 

indicates whether an acknowledgement is requested when the message is read. 
"l"b yes 
"0"b no 

mbzl, mbz 

are not used and must be set to "0"b. 



Name: send message 

This subroutine sends an interactive message to be received by the message facility. If 

the recipient is not currently accepting messages, the message is added to that user's 
mailbox. 
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USAGE 

declare send_message_ entry (char (*) , char (*) , char (*) , fixed bin (35)). 

call send__message_ (person, project, message, code); 

ARGUMENTS 

person 

is the registered Person_id of the recipient (Input) 
project 

is a Projected on which the recipient is registered. (Input) 
message 

is the text of the message to be sent (Input) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$messages_def erred 

recipient is deferring messages. The message is added to his mailbox, but the 

recipient will not receive it immediately. 
error_table_$messages_of f 

recipient is not logged in or not accepting messages. The message is added to 

his mailbox, but the recipient will not receive it immediately. 
error_table_$noentry 

no mailbox for the specified recipient 
error_table_$no_append 

insufficient access to add a message to the recipient's mailbox. 
error_table_$wakeup_denied 

insufficient access to send the message interactively; the message is added to 

the recipient's mailbox. 
error_table_$no_inf o 

access class restrictions prevent the sender from finding out whether the 

message was sent 

NOTES 

The pathname of the mailbox sent to is: 

>udd>Project_i d>Person_id>Person_id.mbx 



2-727 



AG93-05 



send_message_ 



send_message_ 



Entry: send_message_$acknowledge 

This entry point sends a message to be acknowledged when read by the recipient. 



declare send_message_$acknowl edge entry (char (*) , char (*) , char (*) , 
fixed bin (35) ) 5 

call send_message_$acknowl edge (person, project, message, code); 

ARGUMENTS 

person 

is the registered Person_id of the recipient. (Input) 
project 

is a Project_id on which the recipient is registered. (Input) 
message 

is the text of the message to be sent (Input) 

code 

is a standard status code. (Output) 
NOTES 

The acknowledgement is an interactive message of the form: 
Acknowl edged 

if the message is printed immediately by the recipient, or: 

Acknowledge message of <time> 
if printed later. 

Entry: send message Sexpress 

This entry point sends a message only if the recipient is logged in and accepting 
interactive messages by means of the accept_messages command. If the message cannot 
be sent interactively, it is not added to the recipient's mailbox. 



USAGE 



USAGE 



declare send_message_$express entry (char («) , char (*) , char («) » 
fixed bin (35)) ; 



ca 1 1 send messa 



ge_$express (person, project 



, message, code) ; 
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ARGUMENTS 
person 

is the registered Person_id of the recipient (Input) 
project 

is a Projected on which the recipient is registered. (Input) 
message 

is the text of the message to be sent (Input) 

code 

is a standard status code. (Output) 



Entry: send message $notify mail 

This entry point sends a mail notification if the recipient is currently accepting 
interactive messages. The mail notification needs to be decoded by the message facility 
(accept_messages), which prints either: 

You have mail from Person_id. Projected 

or for a mailbox other than the default one: 

You have mail from Person_id.Project_id in <path> 



USAGE 

declare send_message_$not i f y_mai 1 entry (char (*) , char (*) , 
f i xed bin (35) ) ; 

call send_message_$not i f y_mai 1 (person, project, code); 

ARGUMENTS 

person 

is the registered Person_id of the recipient. (Input) 
project 

is a Project_id on which the recipient is registered. (Input) 

code 

is a standard status code. (Output) 
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Name: set bit_offset 

This function returns a pointer to the specified bit in the segment referenced by the 
input pointer. 

USAGE 

declare set_bi t_of f set_ entry (ptr, fixed bin (2*0) returns (ptr) 
reducible; 

new_pointe revalue ■ set_bi t_of f set_ (poi nter_val ue, bit_offset); 

ARGUMENTS 

pointer_value 

identifies the segment in which the desired bit resides. (Input) 
bit_offset 

is the offset (relative to the base of the segment) of the desired bit. (Input) 

new_pointer_value 

is the result of this operation. (Output) 

NOTES 

The first bit in a segment has a bit offset of zero. 

If the value of bit_offset is negative or greater than 9,437,183 (the offset of the last 
bit in a 256K word segment), the resulting value of the call is not defined. 



Name: set char offset 

This function returns a pointer to the specified character in the segment referenced by 
the input pointer. 

USAGE 

del set_char_of f set__ entry (ptr, fixed bin (21)) returns (ptr) 
reduc ibl e; 

new_pointer__value = set_char_of f set__ (poi nter_va 1 ue, char_of f set) ; 
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ARGUMENTS 

pointer_value 

identifies the segment in which the desired character resides. (Input) 
char_offset 

is the offset (relative to the base of the segment) of the desired character. 
(Input) 

new_pointer_value 

is the result of this operation. (Output) 

NOTES 

The first character in a segment has a character offset of zero. 

If the value of char_offset is negative or greater than 1,048,575 (the offset of the last 

character in a 256K word segment), the resulting value of the call is not defined. 



Name: set ext variable 

Allows the caller to look up an external variable by name. If the name is not found, 
the variable is added to the list of external variables. 

USAGE 

del set_ext_var i ab 1 e_ entry (char (*) , ptr, ptr, bit(l) aligned, ptr , 

f i xed bin (35) ) ; 

call set_ext__var i abl e_ (ext_name, i ni t__i nf o_ptr , sb_ptr, found__sw, 
node_ptr , code) ; 

ARGUMENTS 
ext_name 

is the name of the external variable. (Input) 
init_info_ptr 

is a pointer to the initialization info (see "Notes on init_info Structure" below). 
(Input) 

sb_ptr 

is a pointer to the base of the stack of the caller. (Input) 
found_sw 

is set to indicate whether the variable was found or not. (Output) 
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node_ptr 

is a pointer to the external variable node (see "Notes on variable_node Structure" 
below). (Output) 

code 

is an error code. (Output) 
NOTES 

When a new external variable is allocated (not found), it must be initialized. 

del 1 init_info aligned based 

2 size fixed bin (19) , 

2 type fixed bin, 

2 i ni t_templ ate 
(init_size refer 

(ini t_info.size) ) fixed bin (35); 

STRUCTURE ELEMENTS 



size 

is the initialization template size in words. 

type 

is the type of initialization to be performed. 
0 no init 

3 init from, template 

4 init area to empty 

init_template 

is the initialization template to be used when type = 3. 



Entry: set ext variable_$locate 

This entry point locates the specified external variable and returns a pointer to the 
structure describing the variable. 

USAGE 

del set_ext__var iable_$ locate entry (char (*) , ptr, ptr , fixed bin (35) ) ; 
call set__ext__var iable_$ locate (ext_name, sb_ptr, node_ptr, code); 
ARGUMENTS 
ext_name 

is the name of the external variable. (Input) 
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sb_ptr 

is a pointer to the base of the stack of the caller. (Input) 
node_pointer 

is a pointer to the variable_node describing the specified variable. This structure 
is defined in the system_link_names.incl.pll include file, (see "Notes" above) 
(Output) 

code 

is an error code. (Output) 



Entry: set ext variable__$pointer 

allows the caller to create a system external variable using list_init_ pointer 
intialization. 

USAGE 

declare set_ext_var i abl e_$poi nter entry (char (*) , ptr, ptr, 
ptr bit(l) aligned, ptr, fixed bin(35))» 

call set_ext_yari abl e_$po inter (ext_name, i ni t_i nf o_ptr , sb_ptr, 
seg_ptr, found__sw, node_ptr, code); 

ARGUMENTS 

ext_name 

is the name of the external variable. (Input) 
init_info_ptr 

is a pointer to the initialization info (see "Notes on init_info Structure"). (Input) 
sb_ptr 

is a pointer to the base of the stack of the caller. (Input) 
seg_ptr 

is a pointer to the segment containing the object to be initialized. (Input). 
found_sw 

is set to indicate whether the variable was found or not (Output) 
node_ptr 

is a pointer to the external variable node, (see "Notes on variable_node 
Structure") (Output) 

code 

is an error code. (Output) 
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Entry: set_ext__variable__$star_heap 

allows the caller to look up heap variables by name. If the name is not found, the 
variable is created and added to the list of heap variables. 

USAGE 

declare set_ext_var i abl e_$star_heap entry (char (*) , ptr, ptr, 
ptr bit(l) aligned, ptr, fixed bin (35) ) S 

call set__ext_var i abl e__$star_heap (ext__name, i ni t_i nf o__ptr , sb_ptr, 
seg_ptr, found_sw, node_ptr, code); 

ARGUMENTS 

ext_name 

is the name of the external variable. (Input) 
init_info_ptr 

is a pointer to the initialization info (see "Notes on init_info Structure"). (Input) 

cK r\t-r 

is a pointer to the base of the stack of the caller. (Input) 
seg^ptr 

is a pointer to the segment containing the object to be initialized. (Input). 
found_sw 

is set to indicate whether the variable was found or not (Output) 
node_ptr 

is a pointer to the external variable node, (see "Notes on variable_node 
Structure") (Output) 

code 

is an error code. (Output) 
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NOTES ON INIT INFO STRUCTURE 



When a new external variable is allocated (not found), it must be initialized. The 

following structure, described in system_link_init_info.incl.pll, is pointed to by 
init_info_ptr: 

del 1 init_info aligned based, 

2 size fixed b i n (19) , 

2 type fixed bin, 
2 i ni t_templ ate 
(ini t_size refer 

(i ni t_i nf o. s i ze) ) fixed b i n (35) J 



STRUCTURE ELEMENTS 



size 

is the initialization template size, in words. 



type 

is the type of initialization to be performed. 

0 no init 

1 invalid 

2 invalid 

3 init from template 

4 init area to empty () 

5 list_template intialization (see "Notes on list_template Initialization Structure"). 
init_template 

is the initialization template to be used when type * 3. 
NOTES ON LISTJEMPLATE INITIALIZATION STRUCTURE 

When the initialization type is 5 or a list_template initialization is being performed 
the init_info structure is not used. The structure used is the list_init_info structure 
which has the following definition in system_link_init_info.incl.pll : 

del 1 1 i st_i ni t__i nfo aligned based, 

2 size 
2 type 
2 pad 

2 1 i st__s i ze 
2 template 



fixed bin (35) » 
fixed bin, 
bit (18) unaligned, 
fixed bin (18) 
uns i gned una 1 i gned , 
(0 refer 

(lis t_ init info. list size)) 
bit (36) ; " 
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STRUCTURE ELEMENTS 



size 

is the size of the variable in words. 



type 

is the type of initialization to be performed. 5 list_template 
list_size 

is the number of list_template_entries that make up the template, 
template 

takes the form of a list_template_entry structure as defined in 
system_link_init_info.incl.pll. This structure is passed on to list_init_ and decoded 
into data which is copied to the variable. See the description of list_init_ in the 
Privileged Subroutines Manual for a more complete description. 



NOTES ON VAR I ABLE _NODE STRUCTURE 



Great care should be taken when using the node_ptr. The variable_node structure 
should never be modified. Modifications to the variable_node will have unpredictable 

results. 



A pointer to the following structure is returned by the entry points in this subroutine. 
It is declared in system_link_names.incl.pll. 

del 1 var i abl e_node aligned based, 

2 f orward_thread ptr unaligned, 

2 vbl_size fixed bin (23) unaligned, 

2 init_type fixed bin(ll) unaligned, 

2 time_al located fixed bin (71). 

2 vbl_ptr ptr, 

2 init_ptr ptr, 

2 name_size fixed bin (21) aligned, 

2 name char (nchars refer 

(va r i ab 1 e_node . name_s i ze) ) , 

2 seg__ptr ptr; 



STRUCTURE ELEMENTS 



forward_thread 

is used by the linker to thread this variable to the next. 



vbl_size 

is the size, in words, of this variable. 
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init_type 

is the type of initialization that is performed: 

0 none 

1 invalid 

2 invalid 

3 initialize from template 

4 initialize to an empty area 

5 initialize using a list template (see "Notes on list_template Initialization 
Structure"). 

time_allocated 

is the clock reading at the time this variable was allocated. 
vbl_ptr 

is a pointer to the variable's storage. 

init__ptr 

is a pointer to the initialization template. 
name_size 

is the number of characters in the variable name, 
name 

is the name of the variable. 
seg_ptr 

is a pointer to the segment containing the variables initialization information. 

* 



Name: set lock 

The set_lock_ subroutine enables cooperating processes to coordinate their use of 
shared resources. Often, it is necessary to ensure that only one of the cooperating 
processes at a time executes a critical section of code with respect to a shared 
resource. For example, if the steps used to modify a shared data base leave it 
momentarily in an inconsistent state, then while the data is being modified no other 
process should attempt to modify or examine the data. 



11/86 



2-737 



AG93-05A 



set lock. 



set lock 



A caller -supplied lock word is used for mutual exclusion of processes. This word 
should be declared as bit(36) aligned, and should be set initially to "0"b indicating the 
unlocked state. When the program is about to enter a critical section of code, it calls 
the set_lock_$lock entry point. This entry point places a unique lock identifier for 
the process in the lock word if no other process currently has its lock identifier in 
the lock word. If the lock word already contains the lock identifier of some other 
process, the set_lock_$lock entry point waits for that process to unlock the lock word. 
Since only one process at a time can have its lock identifier in the lock word, that 
process is assured (subject to the conditions stated below) that it is the only process 
currently executing the critical section of code. If many critical sections share the 
same lock word, then only one process can be executing in any of them at a given 
time. Once the critical section has been completed, the program calls the set_lock_$unlock 
entry point to reset the lock to "0"b. 

Successful use of this subroutine requires that all those processes executing critical 
sections of code obey the necessary conventions. These conventions are the following: 

1. The set_lock_ subroutine is the only procedure that modifies the lock word 
with the exception of the procedure that initializes the lock word to "0"b 
before any call to the set_lock_ subroutine is made. 

2. Ail processes issue calls to the sei_iock_$Iock entry point that place the lock 
identifier in the lock word before entering a critical section of code. 

3. All processes issue a call to the set_lock_$unlock entry point that sets the lock 
word to "0"b after completing execution of a critical section of code. 



Entry: set lock__$lock 

This entry point attempts to place the lock identifier of the calling process in the 
given lock word. If the lock word contains "0"b, then the lock word is set to the 
lock identifier of the calling process. If the lock word contains a valid lock identifier 
of another existing process, then the set_lock_$lock entry point waits for this other 
process to unlock the lock word. If the other process does not unlock the lock word 
in a given period of time, the set_lock_$Iock entry point returns with status. If the 
lock word contains a lock identifier not corresponding to an existing process, the lock 
word is overwritten with the lock identifier of the calling process and an indication 
that an overwriting has taken place is returned; the call is still successful, however. 

Relocking an invalid lock implies either a coding error in the use of locks or that a 
process having a lock set was unexpectedly terminated. In either case, the data being 
modified can be in an inconsistent state. If the lock word already contains the lock 
identifier of the calling process, then the set_lock_$lock entry point does not modify 
the lock word, but returns an indication of the occurrence of this situation. The latter 
case may or may not indicate a programming error, depending on the programmer's 
conventions. 
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USAGE 

declare set_l ock_$ 1 ock entry (bi t (36) aligned, fixed bin, 
fixed bin (35)) J 

call set__lock_$lock (lock_word, wait_time, code); 

ARGUMENTS 

lock_word 

is the word to be locked. (Input/Output) 
wait_time 

indicates the length of real time, in seconds, that the set_lock_$lock entry point 
should wait for a validly locked lock word to be unlocked before returning 
unsuccessfully. (Input) A value of -1 indicates no time limit. 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$invalid_lock_reset 

indicates that the lock word was successfully locked, but the lock word 

previously contained an invalid lock identifier that was overwritten. 
error_table_$locked_by_this_process 

indicates that the lock word already contained the lock identifier of the 

calling process and was not modified. 
error_table_$lock_wait_time_exceeded 

indicates that the lock word contained a valid lock identifier of another 

process and could not be locked in the given time limit 
error_table_$no_w_permission 

indicates that calling process does not have proper write permission to 

lock_word. 

NOTES 

The most efficient method for locking a lock is: 

del static_lock_id bit (36) aligned internal static init ( m, b) ; 
del get_lock_id_ entry returns (bit(36) aligned); 
del stacq bui 1 ti n; 

if static_lock_id = ""b then 

static_1ock_id - get_lock_id_() ; 

if stacq (lock_word ; stat ic_Jock_Jd» ""b) 
then code = 0; 

else call set_1 ock_$ 1 ock (lock_word, wait_time, code) 
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The code fragment above will take significantly less time to lock a lock than would 
calls to set_lock_$lock. If it is not already locked by another process, the stacq 
locking builtin is much faster than the subroutine call to set_lock_$lock. Therefore, in 
applications where execution speed is a primary concern use of the code above is 
recommended. In such cases, the subroutine call overhead can be avoided. In cases 
where the lock is already locked, however, the invalid lock detector and waiting 
facilities of set_lock_$lock are needed. 



Entry: set__ lock $unlock 

This entry point attempts to reset a given lock word to "0"b and is successful if the 
lock word contained the lock identifier of the calling process. 

USAGE 

declare set_lock_$unlock entry (bit (36) aligned, fixed bin (35)); 

call set_lock_$unlock (lock_word, code); 

ARGUMENTS 

lock_word 

is the lock word to be reset. (Input/Output) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$lock_not_locked 

indicates that the lock was not locked. 
error_table_$locked_by_other_process 

indicates that the lock was not locked by this process and therefore was not 

unlocked. 

NOTES 

The most efficient method for unlocking the lock is: 

if stacq (lock_word, ""b, stat i c_lock_i d) 
then code = 0; 

else call set_lock_$unlock (lock_word, code); 

The code fragment above will take significantly less time to lock a unlock than would 
calls to set_lock_$unlock. If it is not already unlocked by another process, the stacq 
unlocking builtin is much faster than the subroutine call to set_lock_$unlock. 
Therefore, in applications where execution speed is a primary concern use of the code 
above is recommended. In such cases, the subroutine call overhead can be avoided. In 
cases where the lock is already unlocked, however, the invalid lock detector and 
waiting facilities of set_lock_$unlock are needed. 
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Name: shcs_$set force write limit 

The shcs_$set_force_write_limit entry point sets the write limit of the calling process. 
This limit specifies the maximum number of pages that can be queued for I/O at the 
same time by calls to hcs_$force_write. The default for this limit is 1. 

USAGE 

declare shcs_$set_f orce_wr i te_l imi t entry (fixed bin, fixed bin (35)); 

call shcs_$set_force_wr i te_l imi t (npages, code); 

ARGUMENTS 

npages 

is the maximum number of pages that are allowed to be queued for I/O at the 
same time. (Input) 

code 

is a standard system status code. (Output) 



Name: signal 

The signal_ subroutine signals the occurrence of a given condition. A description of 
the condition mechanism and the way in which a handler is invoked by the signal_ 
subroutine is given in the Programmer's Reference Manual. 

USAGE 

declare signal_ entry options (variable); 
call signal_ (name, mc__ptr, info_ptr, wc__ptr) ; 
ARGUMENTS 
name 

is the name (declared as a nonvarying character string) of the condition to be 
signalled. (Input) 

mc_ptr 

is a pointer (declared as an aligned pointer) to the machine conditions at the time 
the condition was raised. This argument is used by system programs only in order 
to signal hardware faults. In user programs, this argument should be null if a 
third argument is supplied. This argument is optional. (Input) 
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info_ptr 

is a pointer (declared as an aligned pointer) to information relating to the 
condition being raised. The structure of the information is dependent upon the 
condition being signalled; however, conditions raised with the same name should 
provide the information in the same structure. All structures must begin with a 
standard header. The format for the header as well as the structures provided 
with system conditions are described in the Programmer's Reference Manual. This 
argument is intended for use in signalling conditions other than hardware faults. 
This argument is optional. (Input) 

wc_ptr 

is a pointer (declared as an aligned pointer) to the machine conditions at the time 
a lower ring was entered to process a fault. This argument is used only by the 
system and only in the case where a condition that occurred in a lower ring is 
being signalled in the outer ring and when the lower ring has been entered to 
process a fault occurring in the outer ring. This argument is optional. 

NOTES 

If the signal_ subroutine returns to its caller, indicating that the handler has returned 
to it, the calling procedure should retry the operation that caused the condition to be 
signalled. 

The PL/ 1 signal statement differs from the signal_ subroutine in that the above 
parameters cannot 'be provided in the signal statement. Also, for PL/I-defined 
conditions, a call to the signal, subroutine is not equivalent to a PL /I signal statement 
since information about these conditions is kept internally. 



Name: sort items 

The sort_items_ subroutine provides a generalized, yet highly efficient, sorting facility. 
Entry points arc provided for sorting fixed binary (35) numbers, float binary (63) 
numbers, fixed-length character strings, varying character strings, and fixed-length bit 
strings. A generalized entry point is provided for sorting other data types (including 
data structures and data aggregates) and for sorting data into a user-defined order. 

The procedure implements the HEAPSORT algorithm of J. W. J. Williams with the 
| optimization suggested by R. W. Floyd. HEAPSORT does not maintain input order on 
| duplicate keys. 
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The subroutine takes a vector of unaligned pointers to the data items to be sorted and 
rearranges the elements of this vector to point to the data items in correct order. 
Only the pointers are moved or copied into temporary storage; the data items remain 
where they were when sort_items_ was invoked. 1 



Entry: sort items $bit 

This entry point sorts a group of fixed-length unaligned bit strings into bit string 
order by reordering a pointer array whose elements point to the bit strings in the 
group. Bit string ordering guarantees that, if each ordered bit string were converted to 
a binary natural number, the binary value would be less than or equal to the value of 
its successors. 

USAGE 

declare sor t_i tems_$b i t entry (ptr, fixed bin (2k)); 

call sor t_i tems_$b i t (v_ptr, length); 

ARGUMENTS 

v_ptr 

points to the structure containing an array of unaligned pointers to the 
fixed-length unaligned bit strings to be sorted. (Input). The structure is declared 
as follows, where n is the value of v.n: 

del 1 v al i gned, 

2 n fixed bin (18) , 

2 vector (n) ptr unaligned; 

length 

is the number of bits in each string. (Input) 



Donald Knuth, "The Art of Computer Programming", vol. 3, pp 143-149, 149 
(problem 18), 618 (answer to problem 18); 1973, Addison-Wesley Publishing 
Company. 
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Entry: sort items $char 

This entry point sorts a group of fixed-length unaligned character strings into ASCII 
collating sequence by reordering a pointer array whose elements point to the character 
strings in the group. 

USAGE 

declare sort_J tems_$char entry (ptr, fixed bin (2k)); 
call sort__i tems_$char (v_ptr, str i ng_l th) ; 
ARGUMENTS 
v_ptr 

points to the structure containing an array of unaligned pointers to the 
fixed -length character strings to be sorted. (Input). The structure is declared as 
follows, where n is the value of v.n: 

del 1 v al i gned, 

2 n fixed bin (18) , 

2 vector (n) ptr unaligned; 

stringjth 

is the length of each character string. (Input) 



Entry: sort items Sfixed bin 

This entry point sorts a group of aligned fixed binary (35,0) numbers into numerical 
order by reordering a pointer array whose elements point to the numbers in the 
gToup. 

USAGE 

declare sort_i tems_$f i xed_bi n entry (ptr); 
call sort_i tems_$f i xed_bi n (v_ptr) ; 
ARGUMENTS 
v_ptr 

points to a structure containing an array of unaligned pointers to the aligned 
fixed binary (35,0) numbers to be sorted. (Input). The structure is declared as 
follows, where n is the value of v.n: 

del 1 v al i gned, 

2 n fixed bin (18) , 

2 vector (n) ptr unaligned; 
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Entry: sort items $float bin 

This entry point sorts a group of aligned float binary (63) numbers into numerical 
order by reordering a pointer array whose elements point to the numbers in the 
group. 

USAGE 

declare sort__i tems_$f 1oat_bi n entry (ptr) ; 
call sort__i tems_$f loat_bi n (v_ptr) ; 
ARGUMENTS 
v_ptr 

points to the above structure containing an array of unaligned pointers to the 
aligned float binary (63) numbers to be sorted. (Input) 



Entry: sort items Sgeneral 

This entry point sorts a group of arbitrary data elements, structures, or other 
aggregates into a user-defined order by reordering a pointer array whose elements 
point to the data items in the group. The structure of data items, the information 
field or fields within each item by which items are sorted, and the data ordering 
principle are all decoupled from the sorting algorithm by calling a user-supplied 
function to order pairs of data items. The function is called with pointers to a pair 
of items. It must compare the items and return a value that indicates whether the 
first item of the pair is less, than, equal to, or greater than the second item. The 
sorting algorithm reorders the elements of the pointer array based upon the results of 
the item comparisons. 

USAGE 

declare sort_i tems_$general entry (ptr, entry); 
call sort_i tems_$genera1 (v_ptr, function); 
ARGUMENTS 
v_ptr 

points to the structure containing an array of unaligned pointers to the data items 
to be sorted. (Input). The structure is declared as follows, where n is the value 

of v.n: 

del 1 v al i gned, 

2 n fixed bin (18) , 

2 vector (n) ptr unaligned; 
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function 

is a user-supplied ordering function. (Input). Its calling sequence is shown under 
"Notes" below. 

NOTES 

The sort_items_$general entry point calls a user-supplied function to compare pairs of 
data items. This function must know the structure of the data items being compared, 
the field or fields within each item that are to be compared, and the ordering 
principle to be used in performing the comparisons. The function returns a 
relationship code as its value. The calling sequence of the function is as follows: 

declare function entry (ptr unaligned, ptr unaligned) 
returns (fixed bin(l)); 

value = function (ptr_f i rst_i tern, ptr_second_i tern) ; 
where: 

ptr_first_item 

is an unaligned pointer to the first data item. (Input) 
ptr_second_item 

is an unaligned pointer to a data item to be compared with the first data item. 
(Input) 

value 

is the value of the first data item compared to the second data item. (Output). 
It can be: 

-1 the first data item is less than the second. 
0 the first data item is equal to the second. 
+1 the first data item is greater than the second. 

EXAMPLE 

i A simple example of a user-supplied ordering function is shown below. It compares 
pairs of fixed binary (35,0) numbers. If this function is passed to the sort_items_$general 
entry point, it performs the same function as a call to the sort_items_$fixed_bin entry 
point, but with less efficiency because of the overhead involved in calling the 
function. 
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function: procedure (pi, p2) returns (fixed bin(l)); 

declare (pi, p2) ptr unaligned, 

datum fixed bin (35*0) based; 

if pi -> datum < p2 -> datum then 

return (-1) ; 
else if pi -> datum ■ p2 -> datum then 

return ( 0) ; 

el se 

• return (+1) ; 

end function; 



Entry: sort_items Svarying char 

This entry point sorts a group of varying character strings into ASCII collating 
sequence by reordering a pointer array whose elements point to the character strings in 
the group. 

USAGE 

declare sort_i tems_$vary i ng_char entry (ptr); 
call sort_i tems_$vary i ng_char (v_ptr) ; 
ARGUMENTS 
v_ptr 

points to the structure containing an array of unaligned pointers to the varying 
character strings to be sorted. (Input). The structure is declared as follows, where 
n is the value of v.n: 

del 1 v al igned, 

2 n fixed bin (18) , 

2 vector (n) ptr unaligned; 
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Name: sort items indirect 

The sort_items_indirect_ subroutine is a variation of the sort_items_$general entry 
point. It provides a facility for sorting a group of data items, based upon the value 
of an information field that is logically associated with each item but resides at a 
varying offset from the beginning of each item. A name in the name list associated 
with the status block returned by the hcs_$status_ entry point is an example of such 
an information field. 

The sort_items_indirect_ subroutine provides high performance entry points for sorting 
data items by the value of a single fixed binary (35) field, float binary (63) field, 
fixed-length bit string field, fixed-length character string field, or adjustable length 
character string field associated with each item. A generalized entry point is provided 
for sorting other types of information fields, for sorting aggregate information fields, 
or for sorting items into a user-defined order. 

To use the sort_items_indirect_ subroutine, for some entries the caller must create 
three arrays: a vector of pointers to the data items being sorted (the item vector), a 
vector of pointers to the single information field within each item on which the sort 
is based (the field vector), and an array of indices into these two vectors. For other 
entries, only two arrays are required: a vector of pointers to the data items being 
sorted and an array of indices into the vectors. This index array is initialized 
sequentially with integers by sort_items_indirect_, which then reorders these indices to 
index the pointer vectors to the data items in correct order. Only indices are moved 
or copied into temporary storage. Vector elements and data items remain where they 
were when sort_items_indirect_ was invoked. 

This procedure differs from that used in the sort_items_ subroutine in that an array 
of indices into the vector is sorted rather than the vector itself. This allows the caller 
to create two vectors of pointers: one containing pointers to the data items to be 
sorted and one containing pointers to the particular data field within each item on 
which the item is to be sorted. There is a one-to-one correspondence between the 
elements of the data items vector and the elements of the data field within each item 
vector. This correspondence is maintained across the reordering of the index array. 
Thus, the index array provides indices into the sorted list of data fields and also into 
the sorted list of data items containing these fields. 

NOTES 

To use the sort_items_indirect_$adj_char entry point, one additional array must be 
created: an array of lengths of the adjustable length character string information fields 
on which the sort is based. 

For the sake of simplicity, the sort information field is shown as part of the items 
being sorted in each of the diagrams below. A more general application might show 
each item containing a locator variable that addresses the sort field(s) associated with 
that item. The one-to-one correspondence between elements of the item vector and 
elements of the field vector is shown below. 
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The array of indices can be used to reference elements of both vectors. The field 
vector and index array are passed to the sort_items_indirect_ subroutine, which 
references the sorting field in each item through elements of these two arrays, as 
shown below. 



i ndex 



1 



field vector 



i tern 



field 



The sort_items_indirect_ subroutine reorders the index values so that values selected 
sequentially from the index array reference pointer to the elements of a sorted list of 
information fields. Because the sorting process involves only the interchange of index 
values, there is still a correspondence between the elements of the item vector and the 
elements of the field vector after the sort is complete. 
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If the information field upon which the sort is based is located at a known offset 
from the beginning of each item, then the calling program can avoid creating the 
index array and the item vector by using the sort_items_ subroutine. (This subroutine 
cannot process adjustable length fields.) The field vector is passed to the sort_items_ 
subroutine, and then the elements of the item vector are computed by applying the 
appropriate offset to the corresponding field vector elements. 

The procedure implements the HEAPSORT algorithm of J. W. J. Williams with the 
optimization suggested by R. W. Floyd. 1 



Entry: sort items_indirect $adj char 

This entry point sorts a group of information fields, which are unaligned adjustable 
length character strings, into ASCII collating sequence order by reordering an index 
array. The elements in this index array are indices into an array of unaligned pointers 
to the character strings in the group. 

USAGE 

declare sort_i tems_i nd i rect_$adj_char (ptr, ptr, ptr) ; 
call sor t_i tems_i nd i rect_$adj_char (v_ptr, i_ptr, ljptr) ; 



Donald Knuth, "The Art of Computer Programming", vol. 3, pp 143-149, 159 
(problem 18), 618 (answer to problem 18); 1973, Addison-Wesley Publishing 
Company. 
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ARGUMENTS 
v_ptr 

points to a structure containing an array of unaligned pointers to the aligned 
fixed binary (35,0) numbers to be sorted. (Input). The structure pointed to by 
v_ptr is to be declared as follows, where n is the number of elements to be 
sorted. 

del 1 v al i gned, 

2 n fixed bin (18) , 

2 vector (n) ptr unaligned; 

i_ptr 

points to a structure containing an ordered array of fixed binary (18) indices into 
the unaligned pointer array. (Input). The structure pointed to by i_ptr is to be 
declared as follows, where n is the number of elements to be sorted. Since 
sort_items_indirect_ sets the i.n and i.array elements, the user needs not set them 
prior to calling the subroutine. 

del 1 i ali gned, 

2 n fixed bin (18) , 

2 array (n) fixed bin (18) ; 

Lptr 

points to a structure containing an array of lengths of the unaligned adjustable 
length character strings to be sorted. (Input). The structure is declared as follows, 
where n is the number of elements to be sorted. 

del 1 1 ali gned, 

2 n fixed bin (18) , 

2 vector (n) fixed bin (21); 



Entry: sort items indirect $bit 

This entry point sorts a group of information fields, which are fixed-length unaligned 
bit strings into bit string order by reordering an index array. The elements of this 
index array are indices into an array of pointers to the bit strings in the group. Bit 
string ordering guarantees that, if each ordered bit string is converted to a binary 
natural number, the binary value is less than or equal to the value of each of its 
successors. 

USAGE 

declare sort_i tems_i ndi rect_$bi t entry (ptr, ptr, fixed bin (2k) ) ; 
call sort_i tems_i nd i rect_$bi t (v_ptr, i_ptr, length); 
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ARGUMENTS 
v_ptr 

points to the above structure v containing an array of unaligned pointers to the 
fixed-length unaligned bit strings to be sorted. (Input) 

i_ptr 

points to the above structure i containing an ordered array of fixed binary (18) 
indices into the unaligned pointer array. (Input) 

length 

is the number of bits in each string. (Input) 



Entry: sort items indirect $char 

This entry point sorts fixed -length unaligned character strings into ASCII collating 
sequence by reordering an index array whose elements are indices into a pointer array 
that points to the strings. All the strings must be the same length. 

USAGE 

declare sort_i tems_i nd i rect_$char entry (ptr, ptr, fixed bin (21)); 
call sort_i tems_i nd i rect_$char (v_ptr, i_ptr, str i ng_l th) ; 
ARGUMENTS 
v_ptr 

points to the above structure v containing an array of unaligned pointers to the 
fixed-length unaligned character string to be sorted. (Input) 

i_ptr 

points to the above structure i of fixed binary (18) indices into the unaligned 
pointer array. (Input) 

stringjth 

indicates the length of each character string. (Input) 
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Entry: sort_items__indirect_$fixed bin 

This entry point sorts a group of information fields, which are aligned fixed binary 
(35,0) numbers, into numerical order by reordering an index array. The elements of 
this index array are indices into an array of unaligned pointers to the numbers in the 
group. 

USAGE 

declare sort_i tems_i nd i rect_$f i xed_b i n entry (ptr, ptr) ; 
call sort_i tems_i nd i rect_$f i xed_bi n (v_ptr, i_ptr) ; 
ARGUMENTS 
v_ptr 

points to the above structure v containing an array of unaligned pointers to the 
unaligned adjustable length character strings to be sorted. (Input) 

Lptr 

points to the above structure i containing an ordered array of fixed binary (18) 
indices into the unaligned pointer array. (Input) 



Entry: sort items indirect Sfloat bin 

This entry point sorts a group of information fields, which are aligned float binary 
(63,0) numbers, into numerical order by reordering an index array. The elements of 
this index array are indices into an array of unaligned pointers to the numbers in the 
group. 

USAGE 

declare sort_i tems_i nd i rect_$f loat_b i n entry (ptr, ptr); 
call sort_i tems_i ndi rect_$f loat_bi n (v_ptr, i_ptr) ; 
ARGUMENTS 
v_ptr 

points to the above structure v containing an array of unaligned pointers to the 
aligned float binary (63,0) numbers to be sorted. (Input) 

Lptr 

points to the above structure i containing an ordered array of fixed binary (18) 
indices into the unaligned pointer array. (Input) 
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Entry: sort items indirect Sgeneral 

This entry point sorts a group of information fields (which are arbitrary data 
elements, structures, or other aggregates) into a user-defined order. It does this by 
reordering an array of indices into a pointer array. The elements of this index array 
point to the sort information field within the data items of the group. The structure 
and data type of the information field and the data ordering principle are decoupled 
from the sorting algorithm by calling a user-supplied function to order pairs of 
information fields. The function is called with pointers to a pair of fields. It must 
compare the fields and return a value that indicates whether the first field of the pair 
is less than, equal to, or greater than the second field. The sorting algorithm reorders 
the elements of the index array based upon the results of the information field 
comparisons. 

USAGE 

declare sor t_i tems_i nd i rect_$genera 1 entry (ptr, ptr, entry); 
call sort_i tems_i ndi rect_$genera 1 (v_ptr, i_ptr, function): 
ARGUMENTS 
v_ptr 

points to the above structure v containing an array of unaligned pointers to the 
information fields to be sorted. (Input) 

Lptr 

points to the above structure i containing an ordered array of fixed bin (18) 
indices into the unaligned pointer array. (Input) 

function 

is a user-supplied ordering function. (See "Notes" below.) (Input) 
NOTES 

The sort_items_indirect_$general entry point calls a user-supplied function to compare 
pairs of data items. This function must know the structure and data type of the 
information fields, and it must know the ordering principle to be used to compare a 
pair of information fields. The function returns a relationship code as its value. The 
calling sequence of the function is as follows: 

declare function entry (ptr unaligned, ptr unaligned) 
returns (f ixedlbin (1)) ; 

value = function (ptr_l st_f ield, ptr__2nd_f i el d) ; 
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where: 

ptr_lst_field 

is an unaligned pointer to the first information field. (Input) 
ptr_2nd_field 

is an unaligned pointer to an information field to be compared with the first 
information field. (Input) 

value 

is the value of the first information field compared to the second information 
field. (Output). It can be: 

-1 first information field is less than the second. 

0 first information field is equal to the second. 
+1 first information field is greater than the second. 

A simple example of a user-supplied ordering function is shown in the sort_items_ 
subroutine. 



Entry: sort items indirect $varying char 

This entry point sorts a group of information fields, which are varying unaligned 
character strings, into ASCII collating sequence by reordering an index array. The 
elements of this index array are indices into an array of pointers to the character 
strings in the group. 

USAGE 

declare sort_i tems_i nd i rect_$vary i ng_char entry (ptr, ptr) ; 
call sor t_i tems_i nd i rect_$vary i ng_char (v_ptr, i_ptr) ; 
ARGUMENTS 
v_ptr 

points to the above structure v containing an array of unaligned pointers to the 
varying fixed-length character strings to be sorted. (Input) 

i_ptr 

points to the above structure i containing an ordered array of fixed binary (18) 
indices into the unaligned pointer array. (Input) 
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Name: sort seg 

The sort_seg_ subroutine provides entry points for sorting segments and character 
strings. It is the subroutine interface used by the sort_seg command, and provides all 
of the facilities of this command at a subroutine level. 

OVERVIEW OF SORTING 

Segments and strings are sorted by dividing the input characters into sort units. Each 
sort unit is composed of N sort strings, where N is the blocking factor. Sort strings 
are identified in the input by a delimiter, which can be specified in terms of a fixed 
number of characters per sort string, or in terms of delimiting characters which match 
a string or qedx regular expression. When delimiting characters are used, the characters 
themselves are not treated as part of the sort string. They simply end one sort string 
and begin the next. 

Sort units are sorted by comparing specific sort fields in one unit with those of 
another. At least one sort field must be given. However, it may identify the entire 
sort unit, in which case the sort units themselves are compared to perform the sorting. 

Sort fields within a sort unit are located by specifying their starting and ending 
points. These points can be specified in terms of a character index within the sort 
unit (or an index and a length), or in terms of field start and end characters which 
match a caller-supplied string or regular expression. 

By default, all sort fields are treated as ASCII character data, but fields can be sorted 
as integer or numeric fields with sort_seg_ converting the sort fields before sorting. 
Fields can be sorted in ascending or descending ASCII collating sequence. Optionally, 
uppercase letters in the sort data can be treated as lowercase letters for sorting 
purposes, providing a case-insensitive sorting capability. 

After sorting the units, special action can be taken if duplicate sort units (or units 
containing duplicate sort fields) are found in the sorted output. Such duplicate sort 
units may be removed from the sorted output, or may be chosen for output in place 
of the normal sort results. 

For further information about sorting, refer to the description of the sort_seg 
command in the Commands manual. It discusses sort strings, sort units, and sort fields 
in more detail and includes some examples. 
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Entry: sort seg_$seg 

This entry point sorts an entire segment. The sorted output can either replace the 
original segment or be written into a new segment 

USAGE 

declare sor t_seg_$seg entry (char (*) , ptr, char (*) , char (*) , char (*) , 
char (*) , fixed bin (21), fixed bin (21), fixed bin (35)); 

call sort_seg_$seg (caller, ss_info_ptr, in_dir, in_ent, out_dir, 
out_ent, out_len, undel im_char_i ndex , code); 

ARGUMENTS 

caller 

specifies the name of the calling procedure. Temporary segments used for sort 
work space are obtained in the caller's name, and the user may be asked 
questions in the caller's name when errors occur. (Input) 

ss_info_ptr 

points to the ss_info structure described in "Info Structure" below. (Input) 
in_dir 

is the pathname of the directory containing the segment to be sorted. (Input) 
in_ent 

is the entryname of the segment to be sorted. (Input) 
out_dir 

is the pathname of the directory in which the sorted results are to be placed. 
(Input) 

out_ent 

is the entryname of the segment in which the sorted results are placed. The same 
segment can be identified by in_dir/in_ent and out_dir/out_ent, in which case 
the input segment is replaced by the sorted results. (Input) 

out_len 

is the the length in characters of the sorted results. This is useful if the caller 

wants to examine or print the sorted results. The caller need not truncate or set 

the bit count for the output segment; sort_seg_ performs these functions. (Output) 

undelim_char_index 

if characters are found following the last sort string delimiter in the input 
segment, then this is the character index of the first such character in the sorted 
output results. Such undelimited characters always appear at the end of the sorted 
output. It is 0 if no such undelimited characters are found in the input segment. 
(Output) 
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code 

is a system status code. If code is nonzero, then sort_seg_ will already have 
printed an error message via sub_err_. (Output) 



ACCESS REQUIREMENTS 



To use the sort_seg_$seg interface, the user must have read access to the segment 
being sorted, and rw access to the output segment. If the user lacks rw access to the 
output segment, sort_seg_$seg will ask if access should be temporarily set to allow 
sorting. 



INFO STRUCTURE 



The ss_info_ptr argument to sort_seg_ points to a structure which defines the type of 
sorting to be performed, the sort field specifications, and so forth. The caller must 
set all structure elements before calling sort_seg_ entry points. This info structure is 
declared in sort_seg_info.incl.pll: 

del 1 ss_info aligned based (ss_i nf o_ptr) , 
2 header. 

3 vers i on char (8) , 

3 block_si2e fixed bin, 

3 field_count fixed bin, 

3 dupl i cate_mode fixed bin, 

3 mbzl (3) f i xed bin, 
3 del im, 

k type fixed bin, 

k number fixed bin, 

k string char (256) varying, 
2 field (ss_f i eld_count refer (ss_i nf o. f i el d_count) ) , 

3 from like ss_i nf o.del im, 

3 to like ss_i nf o.del im, 
3 modes, 

(h descending bit(l), 

h non_case_sensi tive bit(l), 

h numer i c b i t (1) , 

k i nteger b i t (1) , 

h mbzl bit (32)) unal ; 

STRUCTURE ELEMENTS 



version 

is the version number of this structure. The current version is 1. This version is 
represented by the character string value stored in the SS_info_version_l constant. 
Use this constant in setting the version number. 

block_size 

specifies the number of sort strings to be used in forming each sort unit. The 

input is divided into sort strings according to the specifications given in 

ss_info.delim. The block_size value must be 1 or larger. 
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field_count 

specifies the number of sort fields defined for each sort unit At least 1 field 
must be defined. It can define all or part of the sort unit to be the sort field. 

duplicate_mode 

specifies how duplicate sort units, or units containing duplicate sort fields, are to 
be treated as part of the sorting process. Values which may be assigned to this 
element are defined by the following named constants: 

SS_duplicate 

retains duplicate sort units in the sorted results. 
SS_unique 

deletes duplicate sort units from the sorted results. 
SS_only_duplicates 

only duplicated sort units appear in the sorted results. One unit from each 
set of duplicate sort units is placed in the results, in sorted order. This is a 
means of identifying and returning only the duplicates. 

SS_only_duplicate_keys 

only sort units which have duplicate sort fields appear in the sorted results. 
All units from each set of sort units having duplicate fields are placed in the 
results, in sorted order. This provides a means of identifying and returning 
sort units which have the same sort fields. 

SS_unique_keys 

deletes sort units having duplicate sort fields from the sorted results. For 
each set of sort units having duplicate sort fields, only the first appears in 
the sorted results, along with nonduplicate sort units. 

SS_only_unique 

only sort units which are unique appear in the sorted results. Whenever a set 
of duplicate units are found, they are removed entirely from the output. 

SS_only_unique_keys 

only sort units which have unique sort fields appear in the sorted results. All 
units having duplicate sort fields are removed entirely from the output. 

mbzl 

must be set to 0. 

delim.type 

specifies the type of delimiter to be used in dividing the input into sort strings. 
Allowable values are: 

SSJength 

specifies that the input is to be divided into fixed length sort strings. 
delim.number specifies the length of each sort string. 
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SS_string 

specifies that the input is to be divided into sort strings by the character 
string contained in delim. string. The first sort string consists of characters 
from the beginning of the input up to the first instance of this delimiter 
string. Subsequent sort strings consist of the characters following the delimiter 
string for the previous unit, up to the next instance of the delimiter string in 
the input. Note that the delimiter string itself does not appear in any sort 
string. 

SS_reg_exp 

specifies that the input is to be divided into sort strings by character strings 
which match the qedx regular expression contained in delim.string. Division 

occurs as for SS_string, except that regular expression matching is used 

instead of simple string comparision to find the delimiter strings. The 

delimiter strings matching the qedx regular expression do not appear in any 
sort string. 

delim. number 

specifies the length of each sort string, as described under the SS_length case of 
delim. type above. 

delim.string 

specifies the delimiter string or delimiter regular expression, as specified under the 
SS_string and SS_reg_exp cases of delim. type above. 

field 

is an array of structures which defines the sort fields within each sort unit used 
to compare sort units. Each field is specified in terms of a starting location, 
ending location, and comparison modes. At least 1 field must be specified. To 
define the entire sort unit as a field, specify the following: 

field(l).from.type = SS_index; 
field(l).from.number = 1; 
field(l).to.type - SSJength; 
field(l).to.number « -1; 

field, from, type 

specifies the type of starting locator used to define the sort field. Allowable 
values are: 
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SS_index 

specifies that the character index given in field.from.number is the first 
character of the sort field. If the sort unit is shorter than this character 
index, then the unit is sorted as if the field consisted of space characters. 

SS_string 

specifies that field.from.string contains a character string which identifies the 
start of the sort field. The field begins with the first character following the 
first occurrence of this string in the sort unit. If the string does not appear 
in the sort unit, then the unit is sorted as if the field consisted of space 
characters. 

SS_reg_exp 

specifies that field. from.string contains a qedx regular expression. The sort 
field begins with the first character following the first string of the sort unit 
which matches this regular expression. If no match is found in the sort unit, 
then the unit is sorted as if the field consisted of space characters. 

field.from.number 

specifies the character index within the sort unit of the first character of the sort 
field, as described under the SS_index case of field. from, type above. 

field. from.string 

specifies the field start string or regular expression, as described under the 
SS_string and SS_reg_exp cases of field, from, type above. 

field, to. type 

specifies the type of ending locator used to define the sort field. Allowable 
values are: 

SSJength 

specifies that the sort field will have a fixed length, field. to. number specifies 
the number of characters in the sort field. If the sort unit is too short to 
hold a field of this length, then the unit is sorted as if the field were 
extended on the right with space characters to the fixed field length. If a 
length of -1 is specified, then the sort field extends to the end of the sort 
unit. 

SS_index 

specifies that the character index given in field. to.number is the last character 
of the sort field. If the sort unit is shorter than this character index, then 
the unit is sorted as if the field were extended on the right with space 
characters to the specified character position. If the field starting location 
falls after the ending character index, then the unit is sorted as if the field 
consisted of space characters. 
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SS_string 

specifies that field, to. string contains a character string which identifies the end 
of the sort field. The field ends with the first character preceding the first 
occurrence of this string following the field starting location in the sort unit. 
If the string does not appear in the sort unit following the field starting 
location, then the unit is sorted as if the field contained space characters. 

SS_reg_exp 

specifies that field, to. string contains a qedx regular expression. The sort field 
ends with the first character preceding the first string of the sort unit 
following the field starting location which matches this regular expression. If 
no match is found, then the unit is sorted as if the field consisted of space 
characters. 

field, to. number 

specifies the character index within the sort unit of the last character of the sort 
field, as described under the SS_index case of field, to. type above; or specifies the 
character length of the sort field, as described under the SSJength case of 
field, to. type above. 

field, to. string 

specifies the field end string or regular expression, as described under the 
SS_string and SS_reg_exp cases of field, to. type above. 

field, modes, descending 

if "l"b, causes the field to be sorted in descending ASCII collating sequence. 
Otherwise, the field is sorted in ascending sequence. 

f ield. modes. non_case_sensi ti ve 

if "l"b, causes the field to be translated to lowercase when field comparisons are 
performed. The actual sort unit remains unchanged. Otherwise, field comparisons 
are performed without translating the field to lowercase. 

field, modes, numeric 

if "l"b, causes the field to be converted to a numeric value (float decimal(59)) 
before field comparisons are performed. 

f ield. modes, integer 

if "l"b, causes the field to be converted to an integer value (fixed bin(71,0)) 
before field comparisons are performed. If neither numeric nor integer are "l"b, 
field comparisons are performed as ASCII character strings. The character string 
representation must be acceptable to the PL/ 1 or Fortran language conversion 
rules. The actual sort field remains unchanged in the sorted results. 

field.modes.mbz2 

must be set to "0"b. 
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NOTES 

A special named constant, SS_unset, can be assigned to duplicate_mode, delim.type, 
field, from, type or field, to. type to indicate that the type has not yet been set. This 
value should not be assigned when sort_seg_ is invoked. It can be used by the caller 
when filling in the structure, based upon control arguments supplied by the user. 

Entry: sort seg Sstring 

This entry point sorts the contents of a character string. The sorted output can either 
replace the original string or be written into another string. 

USAGE 

declare sor t_seg_$str i ng entry (char (*) , ptr, char (*) , char (*) , 
fixed bin (21), fixed bin (21), fixed bin (35)); 

call sor t_seg_$str i ng (caller, ss_info_ptr, in_string, out_string, 
out_len, undel im_char_index, code); 

ARGUMENTS 

caller 

specifies the name of the calling procedure. Temporary segments used for sort 
work space will be obtained in the caller's name, and the user may be asked 
questions in the caller's name when errors occur. (Input) 

ss_info_ptr 

points to the ss_info structure described under the sort_seg_$seg entry point. 
(Input) 

in_string 

is the string to be sorted. (Input) 
out_string 

is the string in which the sorted results are placed. The same string may be given 
for both in_string and out_string, in which case the sorted results overwrite the 
in_string. The out_string may also overlap part of the storage for in_string. 
When the overlapping is partial or complete, the in_string is copied into a 
temporary segment prior to being sorted. (Output) 

out_len 

is the length in characters of the sorted results. (Output) 
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undelim„char„index 

if characters are found following the last sort string delimiter in the input string, 
then this is the character index of the first such character in the sorted output 
results. Such undelimited characters always appear at the end of the sorted 
output. It is 0 if no such undelimited characters are found in the input string. 
(Output) 

code 

is a system status code. If code is nonzero, then sort_seg_ will already have 
printed an error message via sub_err_. (Output) 



Name: spg__util 

The spg_util_ subroutine collects metering information, from the Multics supervisor and 
subtracts it from the previous sample taken. It is normally called by the 
system_performance_graph command. To use this subroutine, access to either the phcs_ 
or the meterin g g ate gate is required. 

USAGE 

declare spg_ut i l_$spg_ut i 1_ (float, float, float, float, float, float, 
float, float, float, char (110), fixed bin, fixed bin) 

call spg_ut i l_$spg_ut i 1_ (pzi, pnmpi , pmpi, pint, ptc, ppf, psf, 
puse_rz, px, string, length, chsw) 

ARGUMENTS 

pzi 

is the percentage of 

pnmpi 

is the percentage of 

pmpi 

is the percentage of 

pint 

is the percentage of 

ptc 

is the percentage of 

ppf 

is the percentage of 
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zero idle time. (Output) 
nonmultiprogramming idle time. (Output) 
multiprogramming idle time. (Output) 
time in interrupts. (Output) 
time in the traffic controller. (Output) 
time in page control. (Output) 
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psf 

is the percentage of time in segment control. (Output) 
puse_rz 

is the percentage of time executing nonsupervisor code spent in ring zero. 
(Output) 

px 

is no longer used. A value of 0.0 is returned. (Output) 
string 

if the variable chsw is nonzero, string contains upon output a character string that 
describes a new configuration or a new setting of the scheduler tuning parameters. 
(Output) 

length 

is the length of the character string "string". (Output) 

chsw 

is a switch that, if zero, indicates normal output; if nonzero, it indicates that 
string and length are valid and should be output. (Output) 



Entry: spg util $reset 

The effect of this call is to reset the internal initialization switch of the subroutine. 
USAGE 

declare spg_ut i l_$reset entry; 
call spg_ut i l_$reset ; 
ARGUMENTS 

There are no arguments. 
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Name: spg ring 0 info 

The spg_ring_0_info_ subroutine returns information about the virtual CPU time spent 
in the three main gates into ring zero. The three gates are hcs_, phcs_, and hphcs_. 
To use this subroutine, access to either the phcs_ or the metering gate gate is 
required. 

USAGE 

declare spg_r i ng_0_i nf o_ entry (fixed bin (71)); 

call spg_r i ng_0_i nf o (time_rz) ; 

ARGUMENTS 

time_rz 

is the cumulative time, in microseconds, spent in ring zero. (Output) 



Name: ssu 

The ssu_ subroutine provides a set of standard functions for use by application writers 
in developing their own subsystems. Use of ssu_ functions will enable the application 
builder to provide subsystems which are consistent in terms of user interface and 
system response. For detailed instructions on creating subsystems, see "Interactive 
Subsystem Programming Environment" in Section 4 of the Programmer's Reference 
Manual. 



Entry: ssu $abort line 

This entry is used to print an error message and abort the execution of the current 
request line. Additional information on interactive subsystem error handling is 
contained in the Programmer's Reference Manual. 

USAGE 

declare ssu_$abor t_1 i ne entry () options (variable); 

call ssu_$abort__l i ne (sci_ptr, status_code, ioa_string, opt ional_args) ; 
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ARGUMENTS 



sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (input) It must be an aligned (unpacked) pointer. 

status_code 

is the status code for printing a message from an error table. (Input) If it is 
zero, no error table message is printed. It can be any datatype which can be 
converted to fixed bin(35). This argument is optional. 

ioa_string 

is an ioa_ control string used to generate the user message portion of the message 
to be printed. (Input, optional) It can be a varying or non varying character 
string. If it is not present, no user message is printed. 

optional_args 

are arguments to be substituted into the ioa_ control string. (Input, optional) 
They can be of any type required by the control string. 

NOTES 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 

In a standalone invocation, a call to this entry point is translated into a call to 
com_err_ or active_fnc_err_ as appropriate. See the Programmer's Reference Manual 
for information on the use of standalone subsystem invocations. 

The format of the message is as follows: 

subsystem_name (request_name) : Code message User message 

or : 

system_name: Code message User message 

The second form (without the request name) is used when the call is made when no 
request is currently being executed, such as when it is called by the subsystem 
command procedure, rather than a request procedure. 

The "Code message" is the error message associated with the status code. If the code 
argument is omitted or if its value is zero, the "Code message" is omitted, and only 
the "User message" is printed. The "User message" is formed by the appropriate 
substitutions in the ioa_ control string. 
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Entry: ssu $abort_subsystem 

This entry is used to abort the current invocation of the subsystem, and optionally 
print an error message. Additional information on interactive subsystem error handling 
is contained in the Programmer's Reference Manual. 

USAGE 

declare ssu__$abor t_subsystem entry () options (variable); 

call ssu_$abort_subsystem (sci_ptr, status_code, ioa_string, 
opt ional_args) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) It must be an aligned (unpacked) pointer. 

status_code 

is the status code for printing a message from an error table. (Input, optional) If 
it is zero or omitted, no error table message is printed. It can be any datatype 
which can be converted to fixed bin(35). 

ioa_string 

is an ioa_ control string which will be used to generate the user message portion 
of the message to be printed. (Input, optional) It can be a varying or nonvarying 
character string. If it is not present, no user message is printed. 

optional_args 

are arguments to be substituted into the ioa_ control string. (Input, optional) 
They can be of any type required by the control string. 

NOTES 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 

In a standalone invocation, a call to this entrypoint is translated into a call to 
com_err_ or active_fnc_err_ as appropriate. See the Programmer's Reference Manual 
for information on the use of standalone subsystem invocations. 
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The format of the message is as follows: 

subsystem__name (request_name) : Code message User message 

or : 

subsystem_name: Code message User message 

The second form (without the request name) is used when the call is made when no 
request is currently being executed, such as when it is called by the subsystem 
command procedure, rather than a request procedure. 

The "Code message" is the error message associated with the status code. If the code 
argument is omitted or if its value is zero, the "Code message" is omitted, and only 
the "User message" is printed. The "User message" is formed by the appropriate 
substitutions in the ioa_ control string. 



Entry: ssu_$add_info dir 

This entry adds a new directory at the specified location in the list of info directories 
being searched by this subsystem invocation. Additional information on interactive 
subsystem self -documentation facilities is contained in the Programmer's Reference 
Manual. 

USAGE 

declare ssu_$add_i nf o_d i r entry (ptr, char (*) , fixed bin, fixed 
bin (35)) ; 

call ssu_$add_i nf o_d i r (sci_ptr, info_dir, position, code); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

info_dir 

is the pathname of the directory to be added to the list of info directories for 
this invocation. (Input) 

position 

is the position in the list where the info dir is to be added. (Input) It can be 
any positive integer. The new directory will become the Nth entry in the list of 
info directories (i.e., it is added before the directory already present in position 
N). To add a directory at the end, position should be specified as a large 
number, such as 100000, which will guarantee its being added after the last info 
directory. 
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code 

is a storage system status code. (Output) If it is zero, the directory was valid and 
was added; otherwise, it indicates the nature of difficulty associated with the 
directory. 

NOTES 

This entry point validates the existence of the specified info directory, and refuses to 
add it, returning a nonzero status code, unless it is valid. The user must have "s" 
access to the directory in order to add it as an info directory. 



Entry: ssu $add request table 

This entry adds a new request table at the specified location in the list of request 
tables being searched by this subsystem invocation. Addition information on the use of 
interactive subsystem request tables is provided in the Programmer's Reference Manual. 

USAGE 

declare ssu_$add_request_tabl e entry (ptr, ptr, fixed bin, fixed 
bin (35)) ; 

call ssu_$add_request_tabl e (sci_ptr, request_tabl e_ptr , position, 
code) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_in vocation. (Input) 

request_table_ptr 

is a pointer to a valid subsystem request table, to be added to the list searched 
for this invocation. (Input) 

position 

is the position in the list where the request table is to be added. (Input) It can 
be any positive integer. The new request table will be added as the Nth entry in 
the request tables list (i.e., it is added after the request table already present in 
position N. To add a request table at the end, position should be specified as a 
large number, such as 100000, which will guarantee its being added after the last 
request table. 

code 

is a status code. (Output) If it is zero, the table was valid and was added; or 
ssu_et_$invalid_request_table if it was not. 
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NOTES 



This entry point validates the existence and validity of the specified request table, and 
refuses to add it, returning a nonzero status code, unless it is valid. 



Entry: ssu Sapply request util 

This entry is a utility procedure for implementing subsystem "apply" requests. The 
apply request is defined to create a Multics command line out of some or all of its 
request arguments, concatenate the pathname of a segment containing the specified 
object in the subsystem, and call the command processor. It can be used, for instance, 
to allow a user to edit a text file with the editor of her choice, with a request like 
"apply ted -pathname", which would be passed to the command processor as: 

ted -pathname PATHNAME_OF_TEMP_SEG 

If the apply request can take arguments which are meaningful to the subsystem, they 
must all come before the first argument which is to become part of the command 
line. It is recommended that the syntax of the apply request be designed so that the 
first argument which is not a control argument is taken as the beginning of the 
command line; its index will be passed as first_command_arg below. The temp_seg_ptr 
should point to a segment on which the bitcount can be set, or which is already set. 
It is recommended that the segment used for this purpose be obtained by calling 
ssu_$get_temp_segmen t. 

This entry returns no error code; rather, since it is only useful in implementing the 
apply request, it simply calls ssu_$abort_line if it encounters any serious errors, and 
prints a more informative message than could otherwise have been described by an 
error code. 

USAGE 

declare ssu_$appl y_request_ut i 1 entry (ptr, fixed bin, ptr, 
fixed bin (21) , fixed bin (21)) ; 

call ssu_$appl y_request_ut i 1 (sci_ptr, f i rst_command_arg , temp_seg_ptr , 
input_lth, output_lth); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

first_command_arg 

is the index of the first request argument which is to become part of the 
command line. (Input) If the subsystem apply request accepts no subsystem 
arguments, this should be 1; otherwise, it should be the index of the first 
non -control argument to the apply request. 
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temp_seg_ptr 

is a pointer to the segment containing the data to be manipulated by the 
command line. (Input) Its pathname will be determined, and concatenated onto 
the end of the command line. 

input_lth 

is the length, in characters, of the data in the segment, or -1. (Input) If it is 

non-negative, the bitcount of the segment is set to nine times input_lth before 

the command line is executed; otherwise, the bitcount is not altered. If the 
bitcount is set to correspond to input_lth, it will be restored to its previous value 

after the command line has been executed and after output_lth has been set to 
reflect its value. 

output_lth 

is the length, in characters, (derived from the bitcount) of the data in the 
segment, after the command line has been executed. (Output) 



Entry: ssu $arg count 

This entry is used to determine how many arguments a subsystem request received. 
USAGE 

declare ssu_$arg_count entry (ptr, fixed bin); 
call ssu_$arg_count (sci_ptr, arg_count) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

arg_count 

is the number of arguments the request received. (Output) 
NOTES 

This entry point should only be used by requests which can not be invoked as an 
active request. If called by an active request, this entrypoint will abort the request 
line with the message: 

This request can not be used as an active function. 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 
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ssu 



In a standalone procedure, a call to this entry point is translated into a call to 
cu_$arg_count. See the Programmer's Reference Manual for information on the use of 
standalone subsystem invocations. 



Entry: ssu $arg list ptr 

This entry can be used by a subsystem request to get a pointer to its request 
argument list. This argument list is identical to that supplied to a Multics command 
by the command processor: a series of non varying character arguments followed by a 
varying character string argument if the request is invoked as an active request. 

The argument list can be manipulated with calls to cu_$arg_count_rel, cu_$arg_ptr_rel, 
and cu_$af_return_arg_rel, which are equivalent to ssu_$arg_count, ssu_$arg_ptr, and 
ssu_$return_arg for this application. 

USAGE 

declare ssu_$arg_l i st_ptr entry (ptr, ptr); 
call ssu__$arg_l i st_ptr (sci_ptr, arg_l i st_ptr) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

arg_list_ptr 

is a pointer to the request argument list. (Output) 
NOTES 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 



Entry: ssu $arg ptr 

This entry is used by the procedure implementing a subsystem request to access its 
arguments. 

USAGE 

declare ssu_$arg_ptr entry (ptr, fixed bin, ptr, fixed bin(21)); 
call ssu_$arg_ptr (sci_ptr, arg_index, arg_ptr, arg_lth); 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

arg_index 

is the index of the argument to be accessed. It must be between one and the 
number of arguments supplied to the request. (Input) 

arg_ptr 

is a pointer to the selected argument, as a character string. (Output) 
arg_lth 

is the length of the selected argument, as a character string. (Output) 
NOTES 

If asked for an argument whose index exceeds the request's argument count, this entry 
point will abort the request line with the message: 

Expected argument missing. 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 

In a standalone invocation, a call to this entry point is translated into a call to 
cu_$arg_ptr or cu_$af_arg_ptr. See the Programmer's Reference Manual for information 
on the use of standalone subsystem invocations. 



Entry: ssu Screate invocation 

This entry is used to create an invocation of a subsystem. The subsystem invocation 
must later be destroyed by a call to ssu_$destroy_in vocation. Additional information 
on interactive subsystems is provided in the Programmer's Reference Manual. 

USAGE 

declare ssu_$create_i nvocat i on entry (char (*) , char (*) , ptr, ptr, 
char (*) , ptr, fixed bin (35)); 

call ssu_$create_i nvocat i on (subsystem_name, version_str i ng, info_ptr, 
request_tab 1 e_ptr , i nfo_d i rectory , sci_ptr, code); 
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ARGUMENTS 



subsystem_name 

is the name of the subsystem. (Input) This name is used in error messages, in the 
output of the "." request (if any), as the default prompt, and as the default 
exec_com suffix. 

version_string 

is the name of the current version of the subsystem, such as "4.3j". (Input) It is 
used in the output of the request 

info_ptr 

is a pointer to the invocation info structure specific to this subsystem. (Input) It 

points to a data structure containing all the information which must be passed 

between the command procedure and the request procedures for this invocation. 

request_table_ptr 

is a pointer to the request table used for this subsystem, or null. (Input) If it is 
null, there are no request tables for the subsystem invocation, and if any are 
desired, they must be added by calls to ssu_$add_request_table. At least one 
request table is required for processing of any requests. 

info_directory 

is the name of a directory in which the help and list_help requests (if any) will 
look for info files on the subsystem. (Input) If this is the null string, and no 
info directories are later added by calling ssu_$add_inf o_directory, the help and 
list_help requests will not operate. 

sci_ptr 

is a pointer to the subsystem control structure created for this invocation. 
(Output) 

code 

is a status code; if it is nonzero, the subsystem invocation could not be created, 
and processing should not continue. (Output) 



Entry: ssu Sdelete info dir 

This entry is used to delete a directory from the list of info directories being 
searched. The specified info directory must be in the list. In order to avoid 
confusion about pathnames, the comparison is done by filesystem unique ID, if that 
can be determined, otherwise by literal pathname. If the directory is not present, a 
nonzero status code is returned. 

USAGE 

declare ssu_$del ete_i nf o_d i r entry (ptr, char (*) , fixed bin(35)); 
call ssu_$del ete_i nf o_d i r (sci_ptr, info_dir, code); 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

info_dir 

is the name of the directory to be deleted. (Input) 

code 

is a status code. (Output) It is zero if the specified info directory was found in 
the list, or error_table_$noentry if not. 



Entry: ssu Sdelete request table 

This entry is used to delete a request table from the list of tables being searched. 
The specified request table must be in the list If it is not present, a nonzero status 
code is returned. 

USAGE 

declare ssu_$de) ete_request_tabl e entry (ptr, ptr, fixed bi.n(35))» 
call ssu_$delete_request_table (sci_ptr, request_tabl e_ptr , code); 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

request_table_ptr 

is a pointer to the request table io be deleted, (input) It is not checked for 
validity, or whether it points to a valid request table, so that invalid request table 
pointers can be removed from the list. 

code 

is a status code. It is zero if the specified request table pointer is found in the 
list, or ssu_et_$request_table_not_found if not. (Output) 
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Entry: ssu Sdestroy invocation 

This entry is used to destroy a subsystem invocation created by a previous call to 
ssu_$create_invocation or ssu_$standalone_invocation. 

USAGE 

declare ssu_$destroy_i nvocat i on entry (ptr) ; 
call ssu_$destroy_i nvocat i on (sci_ptr); 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

NOTES 

If sci_ptr is null on input, the call is ignored. This entry point sets sci_ptr to null 
after destroying the invocation. 



Entry: ssu $evaluate active string 

This entry is used to interpret a single active request string. It is the subsystem 
equivalent to cu_$evaluate_active_string. 

USAGE 

declare ssu_$eva 1 uate_act i ve_s tr i ng entry (ptr, ptr, char (*) , fixed bin, 
char («) varying, fixed bin (35)); 

call ssu_$eva 1 uate_act ive_str i ng (sci_ptr, rp_opt i ons_ptr , 
act i ve_str i ng, string_type, return_va 1 ue, code); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

rp_options_ptr 

if null, specifies that the request processor options in effect for this subsystem 
are used. Otherwise, it locates an rp_options structure defining the options to be 
used to evaluate the active string. 

active_string 

is the active string to be evaluated. (Input) It should not include the outermost 
brackets. 
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string_type 

specifies the type of active string to be evaluated. (Input) It must be one of the 
following values defined in the include file cp_active_string_types.incl.pll: 

NORMAL_ACTIVE_STRING 

the active string return value should be rescanned for all command processor 

constructs. ([...]) 
TOKENS_ONLY_ACTIVE_STRING 

the active string return value should be rescanned only for whitespace and 

quotes. ( | [ • . • ] ) 
ATOMIC_ACTIVE_STRING 

the active string return value should not be rescanned. ( | | [ . • • ] ) 

return_value 

is the result of the evaluation of the active string. (Output) 

code 

is a standard status code. If the standard evaluate_active_string procedure is being 
used, it will have one of the following values; if a user supplied procedure is in 
use, the list can be different. (Output) 
0 

indicates that the active string was successfully evaluated. 

error_table_$command_line_overflow 

indicates that the return value of the active string was too large to fit in the 
supplied return_value argument; as much as would fit is returned, however. 

ssu_et_$request_line_aborted 

indicates that evaluation of the active string was terminated by a call to 
ssu_$abort_line. This usually indicates that an error was encountered by one 
of the active requests; however, the error message has already been printed, 
so no message should be printed by the caller of ssu_$evaluate_active_string. 

ssu_et_$subsystem_aborted 

indicates that evaluation of the active string was terminated by a call to 
ssu_$abort_subsystem; this generally indicates that the subsystem should be 
terminated, and no further processing be done. In any case, no error message 
should be printed. 

anything else 

indicates a serious error condition occurred while trying to evaluate the active 
string. 

NOTES 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 

In a standalone invocation, a call to this entrypoint is translated into a call to 
cu_$evaluate_active_string. See the Programmer's Reference Manual for information on 
the use of standalone subsystem invocations. 
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Entry: ssu $execute_Jine 

This entry is used to intepret a single request line. 
USAGE 

declare ssu_$execute_l i ne entry (ptr, ptr, fixed bin(21), fixed 
bin (35)); 

call ssu_$execute_l i ne (sci_ptr, request_l i ne_ptr , request_l i ne_l th , 
code) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

request_line_ptr 

is a pointer to the request line to be executed. (Input) 

request_line_lth 

is the length of the request line, in characters. (Input) 

code 

is a standard status code. (Output) If the default execute_line procedure is being 
used, it can have one of the following values; these can be different if a user 
procedure is being used for this function. 
0 

the request line was executed successfully, and returned normally. 
ssu_et_$null_request_line 

the request line was "blank", in the command_processor_ sense, i.e., contained 

no requests, iteration or brackets, but was merely a mixture of whitespace 

and semi-colons. 
ssu_et_$request_line_aborted 

the request line was terminated during its execution by a call to ssu_$abort_line. 

This usually indicates that an error was encountered by one of the requests; 

however, the error message has already been printed, so no message should be 

printed by the caller of ssu_$execute_line. 
ssu_et_$subsystem_aborted 

the request line was terminated normally by a call °to ssu_$abort_subsystem; 

this generally indicates that the subsystem should be terminated, and no 

further processing be done. In any case, no error message should be printed. 
ssu_$program_interrupt 

the request line was terminated by the user interrupting its execution and 

using the program interrupt command. The caller of this entry point need 

not print a message, 
anything else 

indicates a serious error condition occurred while trying to execute the request 
line. 
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NOTES 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 

In a standalone invocation, a call to this entry point is translated into a call to 
cu_$cp. See the Programmer's Reference Manual for information on the use of 
standalone subsystem invocations. 



Entry: ssu $execute start up 

This entry point executes the current subsystem's start_up exec_com. 
USAGE 

declare ssu_$execute_star t_up entry () options (variable); 
call ssu_$execute_start_up (sci__ptr, code, opt i ona l_ec_args) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_in vocation. (Input) 

code 

is a standard system status code. (Output) It can have one of the following 

values: 

0 

the start_up exec_com was executed successfully. 
error_table_$noentry 

there is no start_up exec_com for this subsystem. 
ssu_et_$exec_com_abor ted 

execution of the exec_com was abnormally terminated. 
ssu_et_$subsystem_aborted 

execution of the exec_com was abnormally terminated by a call to 

ssu_$abort_subsystem. 

optional_ec_args 

are optional arguments to be passed to the start_up exec_com. (Input) These 
arguments must be either nonvarying unaligned or varying aligned character strings. 

NOTES 

The subsystem's start_up exec_com is a segment named "start_up.ec_suffix" where 
ec_suffix is the subsystem's exec_com suffix. See ssu_$set_ec_suffix for a description 
of how to change the suffix. 
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This en try point searches for the start_up exec_com first in the the user's home 
directory, then in the user's project directory >udd>Project_id, and last in >site 
The first exec_com found, if any, is used. 



Entry: ssu $execute_string 

This entry is used to execute a request string, usually expressed as an in-line constant 
or character string variable. It is provided only as a utility function which allows the 
execution of character strings as strings, rather than by pointer and length. It is 
implemented by a call to ssu_$execute_line; therefore, if ssu_$execute_line is changed, 
ssu_$execute_string will change in exactly the same way. 

USAGE 

declare ssu_$execute_str i ng entry (ptr, char (*) , fixed bin (35)); 
call ssu_$execute_str i ng (sci_ptr, request_str i ng , code); 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

request_string 

is a character string containing the requests to be executed. (Input) 

code 

is a status code. (Output) It can have any of the values specified for 
ssu_$execute_line. The list of error codes is only for the default procedure, and 
can be different if a user procedure is substituted. 



Entry: ssu $get area 

This entry is used to obtain an area for use by the subsystem invocation. It calls the 
define_area_ subroutine to obtain an area in a temporary segment. The difference 
between using this entry and calling define_area_ directly is that areas acquired by 
calling ssu_$get_area are released when the subsystem invocation is destroyed, regardless 
of whether the user program had freed them earlier. Areas acquired by calling 
ssu_$get_area should be released by calling ssu_$release_area. 

USAGE 

declare ssu_$get_area entry (ptr, ptr, char (*) , ptr); 

call ssu_$get_area (sci_ptr, area_i nf o_ptr , comment, area_ptr) ; 
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ARGUMENTS 



sci_ptT 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

area_info_ptr 

is a pointer to an area_info structure (defined in area_info.incl.pll) describing the 
area, or null. (Input) If the area_info_ptr is null, an area with default 
characteristics is defined; see below for details. Only the area_control flags in the 
area_info are used by ssu_$get_area; the area is always put in a temporary 
segment. The area pointer is returned as the final argument to ssu_$get_area; it is 
not written into the area_info structure. 

comment 

is a comment identifying the use to which the area will be put. (Input) It is 
used in constructing the owner name for the call to define_area_, in the form: 

subsys_name.N (comment) 

where subsys_name is the name of the subsystem, N is the invocation level for 
this invocation, and the comment (if any) follows, in parentheses. This is done to 
make it easier to identify the segment names listed by list_temp_segments. 

area_ptr 

is a pointer to the area. (Output) It will always be valid; if for some reason the 
area cannot be acquired, the current request line (or subsystem invocation, if there 
is no request line) is aborted with an appropriate message. No errors are ever 
reflected back to the caller of ssu_$get_area. 

NOTES 

If the area_info_ptr supplied to ssu_$get_area is null, an area with default 
characteristics is created. The area is extensible, initially one segment long, and is 
zero_on_free (but not zero_on_alloc). All other area_control flags are off. 

If the subsystem is in "debug mode" (see description of ssu_$set_debug_mode), all 
areas (both user-specified and default) are created with the dont_free attribute. 
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Entry: ssu $get debug mode 

This entry is used to get the current state of debug mode. Debug mode controls 
several features intended only as an aid to debugging. A description of interactive 
subsystem debug mode is provided in the Programmer's Reference Manual. 

USAGE 

declare ssu_$get_debug_mode entry (ptr) returns (bit(l) aligned); 

debug_mode = ssu_$get_debug_mode (sci_ptr); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

debug_mode 

is the current debug mode, either on or off. (Output) 



Entry: ssu $get__default procedure 

This entry is used to get the default value for a replaceable procedure value. The 
value returned is the procedure which is called to perform the specified function if 
no calls to ssu_$set_procedure are ever made for that procedure. 

USAGE 

declare ssu_$get_def aul t_procedure entry (ptr, char (*) , entry, fixed 
bin (35)); 

call ssu_$get_def aul t_procedure (sci_ptr, procedure_name, 
procedure_val ue, code); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

procedure_name 

is the name of the procedure the value of which is to be returned. (Input) 
procedure_value 

is the default value of the specified replaceable procedure value. (Output) 
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code 

is a status code. (Output) It can have the following values: 
0 

success. 
error_table_$noentry 

procedure_name is not an acceptable value. 

NOTES 

See the Programmer's Reference Manual for the currently defined list of replaceable 
procedure names. 



Entry: ssu $get default rp options 

This entrypoint returns the default request processor options for the current subsystem. 
USAGE 

declare ssu_$qet_def aul t_rp_opt i ons entry (ptr, char (8) , ptr, 
fixed bin (35)) ; 

call ssu_$get_def aul t_rp_options (sci_ptr, vers i on_wanted , 
rp_opt i ons_ptr , code); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

version_wanted 

specifies which version of the rp_options structure is to be returned by this 
procedure. (Input) This argument must have the value of the named constant 
RP_OPIONS_VERSION_l defined in the system include file ssu_rp_options.incl.pll. 

rp_options_ptr 

is a pointer to an rp_options structure previously allocated by the caller which is 
to be filled in by this entrypoint (Input) This structure is declared in the system 
include file ssu_rp_options.incl.pll. 

code 

is a standard system status code. (Output) It can have one of the following 

values: 

0 

the structure was successfully filled in. 
error_table_$unimplemented_version 

the caller requested an unrecognized version of the rp_options structure. 
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NOTES 

See the information on the subsystem request language in the Programmer's Reference 
Manual for a description of the rp_options structure and the request processor options 
mechanism. 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 



Entry: ssu $get ec search list 

This entry returns the name of the search list currently being used to find subsystem 
exec_com files. By default, no search list is used; exec_coms must be specified by full 
pathname, and this value is a null string. See also the description of ssu_$set_ec_search_list. 

USAGE 

declare ssu_$get_ec_search_l i st entry (ptr) returns (char (32)); 
search_l i st_name = ssu_$get_ec_search_l i st (sci_ptr); 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

search_list_name 

is the name of the current exec_com search list or a null string if no search list 
is used by this subsystem invocation. (Return) 



Entry: ssu $get ec subsystem ptr 

This entry returns the pointer currently used to implement the "referencing_dir" rule 
in the search list for subsystem exec_coms. By default, this pointer is null, meaning 
that the refer encing_dir rule has no effect, even if the exec_com search list name is 
non-null. See also the description of ssu_$set_ec_subsystem_ptr. 

USAGE 

declare ssu_$get_ec_subsystem_ptr entry (ptr) returns (ptr) ; 
subsystem_ptr = ssu_$get_ec_subsystem_ptr (sci_ptr) ; 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

subsystem_ptr 

is a pointer to some segment in the directory being used as the subsystem's 
exec_com referencing_dir or null if no such directory is being used. (Output) 



Entry: ssu Sget ec suffix 

This entry returns the suffix currently being used for subsystem exec_com files. By 
default, this string is the subsystem name. See also the description of ssu_$set_ec_suffix. 

USAGE 

declare ssu_$qet_ec_suf f i x entry (ptr) returns (char (32)); 
suf f i x_str i ng = ssu_$get_ec_suf f i x (sci_ptr) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

suffix_string 

is the current exec_com suffix for this subsystem invocation. (Output) 



Entry: ssu Sget info ptr 

This entry is used to get the info_ptr for this subsystem invocation. Normally, this 
value is otherwise available, either as a request parameter, or as a variable in the 
command procedure of the subsystem. This entry is only useful in subroutines which 
are passed only the sci_ptr and not the info_ptr as parameters, such as user supplied 
abort procedures. Additional information on the use of sci_ptr and info_ptr is 
provided in the description of interactive subsystems in the Programmer's Reference 
Manual. 

USAGE 

declare ssu_$get_i nf o_ptr entry (ptr) returns (ptr); 
info_ptr = ssu_$get_i nf o_ptr (sci_ptr); 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

info_ptr 

is the info_ptr for this subsystem invocation. (Output) 



Entry: ssu $get invocation count 

This entry is used to determine the invocation index of the current subsystem 
invocation, and also determine how many invocations of the subsystem are currently 
active. 

USAGE 

declare ssu_$get_i nvocat i on_count entry (ptr, fixed bin, fixed bin); 
call ssu_$get_i nvocat i on_count (sci_ptr, this_level, max_level) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_Screate_in vocation. (Input) 

this_level 

is the invocation index for this subsystem invocation. (Output) 
max_level 

is the invocation index for the highest numbered subsystem invocation presently 
active. (Output) 



Entry: ssu $get level n sci ptr 

This entry is used to examine the state of other invocations of the subsystem by 
returning the info_ptr and sci_ptr for the other invocation. If the level index 
specifies an invocation which does not exist, the info_ptr and sci_ptr are returned as 
null. Additional information on the use of info_ptr and sci_ptr is provided in the 
description of interactive subsystems in the Programmer's Reference Manual. 

USAGE 

declare ssu_$get_l eve l_n_sc i_ptr entry (ptr, fixed bin, ptr, ptr); 

call ssu_$get_l eve l_n_sc i_ptr (sc i_ptr , 1 evel_i ndex, other_sc i_ptr , 
other_i nf o_ptr) ; 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

level_index 

is the index (invocation number, recursion level) of the other invocation of the 
subsystem for which information is desired. 

other_sci_ptr 

is the sci_ptr for the specified invocation of the subsystem. (Output) 
other_info_ptr 

is the info_ptr for the specified invocation of the subsystem. (Output) 



Entry: ssu $get prev sci ptr 

This entry is used to examine the state of other invocations of the subsystem by 
returning the info_ptr and sci_ptr for the immediately previous invocation. If there is 
no previous invocation of the subsystem, the sci_ptr and info_ptr are returned as null. 
Additional information on the use of the info_ptr and sci_ptr is provided the 
description of interactive subsystems in the Programmer's Reference Manual. 

USAGE 

declare ssu_$get_prev_sc i_ptr entry (ptr, ptr, ptr); 

call ssu_$get_prev_sc i_ptr (sci_ptr, previ ous_sc i_ptr , 
previous_i nfo_ptr) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

previous_sci_ptr 

is the sci_ptr for previous invocation of the subsystem. (Output) 

previous_inf o_ptr 

is the info_ptr for previous invocation of the subsystem. (Output) 
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Entry: ssu__$get_procedure 

This entry is used to get the current value for a replaceable procedure value in the 
specified subsystem invocation. The value returned is the procedure which is called to 
perform the specified function. 

USAGE 

declare ssu_$get_procedure en.try (ptr, char (*) , entry, fixed bin (35)) 5 

call ssu_$get_procedure (sci_ptr, procedure_name, procedure_val ue, 
code) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

procedure_name 

is the name of the procedure for which the value is to be returned. (Input) 
procedure_value 

is the current value of the specified replaceable procedure value. (Output) 

code 

is a status code. (Output) It can have the following values: 
0 

success. 
error_table_$noentry 

procedure_name is not an acceptable value. 

NOTES 

See the Programmer's Reference Manual for the currently defined list of replaceable 
procedure names. 



Entry: ssu $get prompt 

This entry is used to get the string currently being used as a prompt. See the 
description of request loops for interactive subsystems in the Programmer's Reference 
Manual for additional information on prompts. 

USAGE 

declare ssu_$get_prompt entry (ptr) returns (char (6^) varying); 
prompt_str i ng = ssu_$get_prompt (sci_ptr) ; 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

prompt_string 

is the current prompt string. (Output) 



Entry: ssu $get prompt mode 

This entry is used to get the current state of prompting in the subsystem. See the 

description of request loops for interactive subsystems in the Programmer's Reference 
Manual for additional information on prompts. 

USAGE 

declare ssu_$get_prompt_mode entry (ptr) returns (bit (36) aligned); 

prompt_mode - ssu_$get_prompt_mode (sci_ptr) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

prompt_mode 

is the current prompt mode. (Output) The individual bits are interpreted as 
f ollows: 

bit 1 ON suppress all prompts. 

bit 2 ON prompt after blank request lines. 

bit 3 ON suppress prompts if there is type ahead. 

There are named constants in the ssu_prompt_modes.incl.pll include file that may 
be used to examine this return value. 



Entry: ssu $get ready mode 

This entry is used to determine the current state of ready processing. See the 

description of request loops for interactive subsystems in the Programmer's Reference 
Manual for additional information on ready processing. 
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USAGE 

declare ssu_$get_ready_mode entry (ptr) returns (bit ( 1 ) aligned)); 

enab I e_sw - ssu_$get_ready_mode (sc i_ptr) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

enable_sw 

is a bit indicating whether or not ready processing is enabled. (Output) If it is 

'T'b, ready processing is being performed; if it is "0"b, ready processing is not 
being performed. 



Entry: ssu $get request name 

This entry is used to determine the primary name (from the request table) of the 
subsystem request currently being executed. If it is the null string, no request is 
currently being executed. 

USAGE 

declare ssu_$get_request_name entry (ptr) returns (char (32)); 
request_name = ssu_$get_request_name (sci_ptr) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

request_name 

is the name of the request currently being executed, or the null string. (Output) 
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Entry: ssu $get request processor options 

This entrypoint returns the request processor options presently in effect for the 
current subsystem. 

USAGE 

declare ssu_$get_request_processor_opt ions entry (ptr, char (8) , ptr, 
fixed bin (35)) ; 

call ssu_$get_request_processor_opt i ons (sci_ptr, vers i on_wan ted , 
rp_opt i ons_ptr , code); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

version wanted 

specifies which version of the rp_options structure is to be returned by this 
procedure. (Input) This argument must have the value of the named constant 
RP_OPIONS_VERSION_l defined in the system include file ssu_rp_options.incl.pll. 

rp_options_ptr 

is a pointer to an rp_options structure previously allocated by the caller which is 
to be filled in by this entry point (Input) This structure is declared in the 
system include file ssu_rp_options.incl.pll. 

code 

is a standard system status code. (Output) It can have one of the following 

values: 

0 

the structure was successfully filled in. 
error_table_$unimplemented_version 

the caller requested an unrecognized version of the rp_options structure. 

NOTES 

See the information on the subsystem request language in the Programmer's Reference 
Manual for a description of the rp_options structure and the request processor options 
mechanism. 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 
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Entry: ssu Sget subsystem and request name 

This entry is used to acquire a string identifying the subsystem and the current 
request, suitable for use in printing error messages or asking questions. If no request 
is currently being executed, the name returned is the name of the subsystem; 
otherwise, it has the following format 

subsystem_name (request_name) 



USAGE 

declare ssu_$get_subsystem_and_request_name entry (ptr) returns 
(char (72) vary i ng) ; 

name = ssu_$get_subsystem_and_request_name (sci_ptr); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

name 

is the name of the subsystem and request currently being executed, as described 
above. (Output) 

NOTES | 

This is a replaceable procedure. See the Programmer's Reference Manual, Order No. | 
AG91, for information on the use of replaceable procedures within interactive | 
subsystems. i 



Entry: ssu Sget subsystem name 

This entry is used to determine the name, supplied in the call to ssu_$create_invocation 
or ssu_$standalone_in vocation, of the subsystem owning the specified invocation. 

USAGE 

declare ssu_$get_subsys tem_name entry (ptr) returns (char (32) ) ; 
subsystem_name = ssu_$get_subsystem_name (sci_ptr); 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

subsystem_name 

is the name of the subsystem owning the current invocation. (Output) 



Entry: ssu $get subsystem version 

This entry is used to determine the version number of the subsystem which was 
supplied as a parameter in the call to ssu_$create_invocation or ssu_$standalone_invocation. 

USAGE 

declare ssu_$get_subsystem_ver s i on entry (ptr) returns (char (32)); 
subsystem_vers i on = ssu_$geL_subsys tem_ver s i on (sci_ptr); 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

subsystem_version 

is the version number of the subsystem owning the current invocation. (Output) 



Entry: ssu $get temp segment 

This entry is used to obtain a temporary segment for use by the current subsystem 
invocation. It calls get_temp_segment_ to acquire the segment. The difference between 
using this entry and calling get_temp_segment_ directly is that segments acquired by 
calling ssu_$get_temp_segment are released when the subsystem invocation is destroyed, 
regardless of whether the user program had freed them earlier. Segments acquired by 
calling ssu_$get_temp_segment should be released by calling ssu_$release_temp_segment. 

USAGE 

declare ssu_$get_temp_segment entry (ptr, char (*) , ptr); 
call ssu_$get_temp_segment (sci_ptr, comment, temp_seg_ptr) ; 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

comment 

is a comment identifying the use to which the segment will be put. (Input) It is 
used in constructing the owner name for the call to get_temp_segment_, in the 
form: 

subsystem_name.N (comment) 

where subsys_name is the name of the subsystem, N is the invocation level for 
this invocation, and the comment (if any) follows, in parentheses. This is done to 
make it easier to identify the segment names listed by list_temp_segments. 

temp_seg_ptr 

is a pointer to the temporary segment. (Output) It will always be valid. If for 
some reason a temporary segment cannot be acquired, the current request line (or 
subsystem invocation, if there is no request line) is aborted with an appropriate 
message. No errors are ever reflected back to the caller of ssu_Sget_temp_segment. 



Entry: ssu $list info dirs 

This entry is used to obtain a list of the info directories currently in use by this 
subsystem invocation. 

USAGE 

declare ssu_$ 1 i st_i nf o_d i rs entry (ptr, ptr, fixed bin, ptr, fixed 
bin (35)); 

call ssu_$ 1 i st_i nf o_d i rs (sc i_ptr , area_ptr, i nfo_d i rs_l i stivers i on, 
idl_ptr , code) ; 

ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

area_ptr 

is a pointer to an area in which the returned list of info directories can be 
allocated. (Input) 
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inf o_dirs_list_version 

is the version of the info_dirs_list structure which the caller expects. The only 
version of this structure which can currently be requested is 
INFO_DIRS_LIST_VERSION_l. (Input) 

idl_ptr 

is a pointer to the info_dirs_list structure described below allocated by this 
entrypoint. (Output) 

code 

is a standard system status code. If the version of the info_dirs_list structure 
requested is not supported, this value will be error_table_$unimplemented_version. 
(Output) 

NOTES 

The info_dirs_list structure and the named constant INFO_DIRS_LIST_VERSION_l are 
defined in the include file ssu_info_dirs_list.incl.pll. 

The info_dirs_list structure is defined as follows: 

del 1 i nf o_d i rs_l i st aligned based (idl_ptr) , 
2 header , 

3 version fixed bin, 

3 n_info_dirs fixed bin, 

2 info_dirs (0 refer (i nf o_d i rs_l i st . n_i nf o_d i rs) ) , 

3 info_dirname char (168) unaligned, 

3 uid bit (36) , 

3 flags, 

k i nf o_d i r_va 1 i d bit(l) unaligned, 

k pad bit (35) unaligned; 

STRUCTURE ELEMENTS 

version 

is the current version of this structure and has the value of the named constant 
INFO_DIRS_LIST_VERSION_l. 

n_info_dirs 

is the number of info directories in use by this subsystem invocation. 

inf o_dirs(i).inf o_dirname 

is the absolute pathname of this directory. 
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info_dirs(i).uid 

is the file system unique ID of this directory if it can be determined; otherwise, 
it is "0"b. 

inf o_dirs(i).inf o_dir_vaiid 

is 'T'b if this info directory is considered valid by the subsystem utilities; 
otherwise, it is "0"b. 



Entry: ssu $list request tables 

This entry is used to obtain a list of the request tables currently in use by this 
subsystem invocation. 

USAGE 

declare ssu_$l ist_request_tables entry (ptr, ptr, fixed bin, ptr, fixed 
bin (35)); 

call ssu_$ 1 i st_request_tabl es (sci_ptr, area_ptr, 
request_tables_l ist_version, rtl_ptr, code); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

area_ptr 

is a pointer to an area in which the returned list of request tables can be 
allocated. (Input) 

request_tables_list_version 

is the version of the request_tables_list structure which the caller expects. The 
only version of this structure which can currently be requested is 
REQUEST_TABLES_LIST_VERSION_l. (Input) 

rdl_ptr 

is a pointer to the request_tables_list structure described below allocated by this 
entrypoint (Output) 

code 

is a standard system status code. If the version of the request_tables_list structure 
requested is not supported, this value will be error_table_$unimplemented_version. 
(Output) 
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NOTES 

The request_tables_list structure and the named constant 
REQUEST JTABLES_LIST_VERSION_l are defined in the include file 
ssu_request_tables_list.incl.pll. 

del 1 request_tabl es_l i st 
2 header, 
3 version 
3 n_tables 
2 tables 
3 table_ptr 
3 flags, 

h table_val id 
k pad 
3 pad 

STRUCTURE ELEMENTS 
version 

is the current version of this structure and has the value of the named constant 
REQUEST jrABLES_LIST_VERSION_L 

n_tables 

is the number of request tables in use by this subsystem invocation. 

tables(i).table_ptr 

is a pointer to this request table. 

tables(i). table__valid 

is "l"b if this request table is considered valid by the subsystem utilities; 
otherwise, it is "0"b. 



Entry: ssu Slisten 

This entry implements the subsystem listener. The interactive subsystem listener is 
described in the Programmer's Reference Manual. 

USAGE 

declare ssu_$listen entry (ptr, ptr, fixed bin (35)) J 
call ssu_$listen (sci_ptr, iocb_ptr, code); 



aligned based (rtl_ptr) , 

fixed bin, 
fixed bin, 

(0 refer (request_tab 1 es_l i st . n_tab 1 es) ) , 
ptr, 

bi t (1) unal i gned, 
bi t (35) unal igned, 
bit (36); 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

iocb_ptr 

is a pointer to the IOCB for the I/O switch from which input lines are to be 
read. If it is null, the default I/O switch, user_input, is used. (Input) 

code 

is a status code. It can never be zero for this entrypoint. If it is 
ssu_et_$subsystem_aborted, it indicates that the subsystem was exited normally, by 
a call to ssu_$subsystem_abort, and is not an error condition. Any other code 
indicates an error condition which prevented the listener from operating. This list 
of codes is only valid if the default listen procedure is being used; it can be 
different if a user listen procedure is in use. (Output) 

NOTES 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedure within interactive subsystems. 



Entry: ssu Sprint blast 

This entry is used to print a "blast" message announcing a new version of the 
subsystem, if the user running the subsystem has not yet used the new version more 
than a certain number of times. This "threshold" value is provided to give the user 
several opportunities to find out what has been changed. See the description of 
interactive subsystem usage monitoring in the Programmer's Reference Manual for 
additional information. 

USAGE 

declare ssu_$pr i nt_bl ast entry (ptr, ptr, fixed bin, char (*) varying, 
fixed bin (35)) ; 

call ssu_$pr i nt_bl ast (sci_ptr, ref_ptr, threshold, bl ast_message, 
code) ; 
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sci_ptr 

is a pointer to the subsystem contTol structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

ref_ptr 

is a pointer used as a referencing_dir argument in the call to hcs_$make_ptr to 

find the usage segment. It is usually codeptr of an entrypoint in the calling 
procedure. (Input) 

threshold 

is the maximum number of times to print a blast message announcing the new 
version for any particular user. (Input) 

blast_message 

is a blast message to be appended to the version announcement message. (Input) 
This might typically be a brief list of the changes in this version of the 
subsystem. If the blast_message is a null string, only the subsystem name and 
version number are printed (if anything is printed at ail). 

code 

is a status code indicating whether the usage was successfully recorded. (Output) 
In general, the code should be ignored, since there is nothing useful the caller 
can do about it. 



Entry: ssu Sprint message 

This entry is used by a request procedure or the subsystem command procedure to 
print an informational, warning, or nonfatal error message. 

USAGE 

declare ssu_$pr i nt_message entry () options (variable); 

call ssu_$pr i nt_message (sci_ptr, status_code, ioa_string, 
opt i onal_args) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

status_code 

is the status code for printing a message from an error table. (Input) If it is 
zero, no error table message is printed. It can be any datatype which can be 
converted to fixed bin(35). 
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ioa_string 

is an ioa_ control string which is used to format the user message portion of the 
message to be printed. (Input, optional) It can be a varying or non varying 
character string. If it is not present, no user message is printed. 

optional_args 

are arguments to be substituted into the ioa_ control string. (Input, optional) 
They can be of any type required by the control string. 

NOTES 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 

In a standalone invocation, a call to this entrypoint is translated into a call to 
com_err_ or active_fnc_err_ as appropriate. See the Programmer's Reference Manual 
for information on the use of standalone subsystem invocations. 

The format of the message is as follows: 

subsystem_name (request_name) : Code message User message 

or : 

subsystem_name: Code message User message 

The second form (without the request name) is used when the call is made when no 
request is currently being executed, such as when it is called by the subsystem 
command procedure, rather than a request procedure. 

The "Code message" is the error message associated with the status code. If the code 
is zero, the "Code message" is omitted, and only the "User message" is printed. The 
"User message" is formed by the appropriate substitutions in the ioa_ control string. 



Entry: ssu Srecord usage 

This entry is used to make an entry in the usage segment to record a use of the 
subsystem, without printing a "blast" message. See the description of interactive 
subsystem usage monitoring in the Programmer's Reference Manual for additional 
information. 

USAGE 

declare ssu_$record_usage entry (ptr, ptr, fixed bin (35)) 5 
call ssu_$record_usage (sci_ptr, ref_ptr, code); 



2-795 



AG93-05 



ARGUMENTS 



sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

ref_ptr 

is a pointer used as a referencing_dir argument in the call to hcs_$make_ptr to 
find the usage segment (Input) It is usually codeptr of an entrypoint in the 
calling procedure. 

code 

is a status code indicating whether the usage was successfully recorded. (Output) 
In general, the code should be ignored, since there is nothing useful the caller 
can do about it. 



Entry: ssu $release area 

This entry is used to release an area previously obtained by a call to ssu_$get_area. It 
can only be used to release areas acquired for the specified subsystem invocation. It 
returns no error code because any errors encountered are simply ignored, and taken 
care of at the time the subsystem invocation is destroyed. 

USAGE 

declare ssu_$release_area entry (ptr, ptr) ; 
call ssu_$rel ease_area (sci_ptr, area_ptr) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

area_ptr 

is a pointer to the area to be released. (Input) 



Entry: ssu $release_temp segment 

This entry is used to release a temporary segment previously acquired by a call to 
ssu_$get_temp_segment. It can only be used to release temporary segments acquired 
for the specified subsystem invocation. It returns no error code because any errors 
encountered are simply ignored, and taken care of at the time the subsystem 
invocation is destroyed. 
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USAGE 

declare ssu_$rel ease_temp_segment entry (ptr, ptr) ; 
call ssu_$rel ease__temp_segment (sci_ptr, temp_seg_ptr) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

temp_seg_ptr 

is a pointer to the temporary segment to be released. (Input) 



Entry: ssu $reset_procedure 

This entrypoint resets a replaceable procedure in the current subsystem to its default 
value. See the Programmer's Reference Manual for information on the use of 
replaceable procedures within interactive subsystems. 

USAGE 

declare ssu_$reset_procedure entry (ptr, char (*) , fixed bin (35)); 
call ssu_$reset_procedure (sci_ptr, procedure_name, code); 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

procedure_name 

is the name of the replaceable procedure which is to be reset. (Input) 

code 

is a standard system status code. (Output) It can have one of the following 

values: 

0 

the replaceable procedure was successfully reset. 
error_table_$noentry 

the supplied procedure name is not the name of a replaceable procedure. 

NOTES 

See the Programmer's Reference Manual for the currently defined list of replaceable 
procedure names. 
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Entry: ssu = $reset = request processor options 

This entrypoint resets the request processor options presently in effect for the current 
subsystem to their default values. 

USAGE 

declare ssu_$reset_request_processor__options entry (ptr) ; 
call ssu_$reset_request_processor_opt ions (sci_ptr) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation (Input) 

NOTES 

See the information on the subsystem request language in the Programmer's Reference 
Manual for a description of the request processor options mechanism. 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 

Entry: ssu Sreturn arg 

This entry is used by a subsystem request procedure to determine whether it has been 
invoked as an active request, and to get a pointer and length for its return value if 
so. The return string should be declared as: 

del return_value char(rv_lth) varying based (rv_ptr) ; 
USAGE 

declare ssu_$return_arg entry (ptr, fixed bin, bit(l) aligned, ptr, 
fixed bin (21)) ; 

call ssu_$return_arg (sci__ptr, arg_count, af_sw, rv_ptr, rv_lth); 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_in vocation. (Input) 

arg_count 

is the number of arguments supplied to this request, not including the final return 
value argument, if any. (Output) 

af_sw 

is a bit indicating whether the request was invoked as a command request or an 
active request. (Output) It is "l"b if an active request, and "0"b otherwise. 

rv_ptr 

is a pointer to the return string if af_sw is "l"b; otherwise, it is null. (Output) 
rvjth 

is the maximum length of the return string. (Output) 
NOTES 

This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 



Entry: ssu Sset debug mode 

This entry is used to set debug mode for the subsystem. Information on the use of 
interactive subsystem debugging facilities is provided in the Programmer's Reference 
Manual. 

USAGE 

declare ssu__$set_debug_mode entry (ptr, bit(l) aligned); 
call ssu_$set_debug_mode (sci_ptr, debug_mode) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

debug_mode 

is the new value for debug mode, either on or off. (Input) 
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Entry: ssu $set ec search list 

This entry is used to set the name of the search list used to find subsystem exec_com 
files. By default, no search list is used, and subsystem exec_coms must be specified by 
full pathname. This is the case if a null string is supplied. See also the descriptions 
of ssu_$set_ec_suffix and ssu_$set_ec_subsystem_ptr. 

USAGE 

declare ssu_$set_ec_search_l i st entry (ptr, char (32) ) ; 
call ssu_$set_ec_search_l i st (sci_ptr, search_l i st_name) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 



is the name of the search list to use for finding subsystem exec_coms in this 
subsystem invocation or a null string if no search list should be used in this 
subsystem invocation. (Input) 



Entry: ssu__$set ec subsystem ptr 

This entry sets the directory used to implement the "referencing_dir" rule in the 
search list for subsystem exec_coms. By default, this pointer is null, meaning that the 
referencing_dir rule has no effect, even if the search list name is non-null. This 
value is ignored if there is no exec_com search list set or if the search list does not 
use the referencing_dir rule. The referencing_dir can be used as a sort of exec_com 
"subsystem directory" to contain standard subsystem exec_coms for this subsystem. See 
also the descriptions of ssu_$set_ec_suffix and ssu_$set_ec_searcb_path- 

USAGE 

declare ssu_$set_ec_subsystem_ptr entry (ptr, ptr); 
call ssu_$set_ec_subsystem_ptr (sci_ptr, subsystem_ptr) ; 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

subsystem_ptr 

is a pointer to a segment which resides in the directory that will be used as the 
exec_com subsystem directory in this subsystem invocation or null if no directory 
is to be used. (Input) This pointer is only used in calls to hcs_$make_ptr and 
hcs_$f s_get_path_name. 



Entry: ssu $set ec__suffix 

This entry is used to set the suffix for subsystem exec_com files in this subsystem 
invocation. By default, this is the name of the subsystem (eg: for the read_mail 
subsystem, subsystem exec_coms would be named XXX.read_mail by default.) See also 
the descriptions of ssu_$set_ec_search_path and ssu_$set_ec_subsystem_ptr below. 

USAGE 

declare ssu_$set_ec_suf f i x entry (ptr, char (32) ) ; 
call ssu_$set_ec_suf f ix (sci_ptr, suf f i x_str i ng) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

suffix_string 

is the string to use as a suffix for subsystem exec_coms in this subsystem 
invocation. (Input) 



Entry: ssu $set info__dirs 

This entry is used to set the list of info directories searched by this subsystem 
invocation. Additional information on the use of interactive subsystem self -documentation 
facilities is provided in the Programmer's Reference Manual. 

USAGE 

declare ssu_$set_i nf o_d i rs entry (ptr, ptr, fixed bin (35)); 
call ssu_$set_i nfo_di rs (sci_ptr, idl_ptr, code); 
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sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

idLptr 

is a pointer to the info_dirs_list structure which is the new list of info 
directories for this subsystem invocation; this structure is described in detail in the 
writeup of ssu_$list_info_dirs, above. The uid and info_dir_valid elements of the 
caller's structure are set appropriately by this call. (Input) 

code 

is a standard system status code. (Output) It can be one of the following: 
0 

indicates that the supplied info directories list was accepted. 
error_table_$unimplemented_version 

indicates that the supplied version of the info_dirs_list structure is not 

supported by this entry, 
any other value 

indicates that one or more directories in the list are not valid; the invalid 
directories are marked by the info_dir_valid bits in the caller's structure. 

NOTES 

Each supplied info directory is validated as described above in the description of 
ssu_$add_info_dir. This entry also fills in the values of the info_dir_valid and uid 
fields of the supplied info_dirs_list structure. 

If all the info directories are valid, the current list is replaced with the newly 
supplied list and a zero status code is returned. Otherwise, if one of the supplied 
info directories is invalid, a storage system status code indicating the difficulty with 
the first invalid directory on the list is returned. If a non-zero code is returned, the 
invalid directories can be identified by examining the info_dir_valid bits. 



Entry: ssu Sset info ptr 

This entry is used to set the info_ptr for this subsystem invocation. 
USAGE 

declare ssu_$set_i nf o_ptr entry (ptr, ptr); 
call ssu_$set_i nf o_ptr (sci_ptr, info_ptr) 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

info_ptr 

is the info_ptr to be used for this subsystem invocation. (Input) 
NOTES 

This entry can be useful, for instance, when the subsystem info structure does not get 
set up until it is known that the call to ssu_$create_invocation succeeded; a null 
pointer can be passed as the info_ptr in the call to ssu_$create_in vocation, and then 
when the subsystem info itself is set up, ssu_$set_info_ptr can be called to set the 
info pointer to point to it. 



Entry: ssu $set procedure 

This entry is used to set the current value of a replaceable procedure in this 
subsystem invocation. It is used when a subsystem wishes to use a function other than 
the standard ssu_ provided interface for the specified function, such as a replacement 
for the request processor. See the Programmer's Reference Manual for information on 
the use of replaceable procedures within interactive subsystems. 

USAGE 

declare ssu_$set_procedure entry (ptr , char (*) , entry, fixed bin (35)); 

call ssu_$set_procedure (sci_ptr, procedure_name, procedure_value, 
code) ; 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

procedure_name 

is the name of the replaceable procedure which is to be set (Input) 

procedure_value 

is the new value for the specified procedure. (Input) 
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code 

is a status code. (Output) It can have the following values: 
0 

success. 
error_table_noentry 

procedure_name is not a acceptable name. 

NOTES 

See the Programmer's Reference Manual for the currently defined list of replaceable 
procedure names. 



Entry: ssu $set prompt 

This entry is used to set the prompt string for the subsystem. See the description of 

interactive subsystem request loops in the Programmer's Reference Manual for 
additional information on prompts. 

/ /c Anc 

declare ssu_$set_prompt entry (ptr, char (64) varying); 
call ssu_$set_prompt (sci_ptr, prompt_str i ng) ; 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

prompt_string 

is the string to use as the prompt from now on. (Input) 



Entry: ssu $set prompt mode 

This entry is used to set the prompting mode for the subsystem. See the description 
of interactive subsystem request loops in the Programmer's Reference Manual for 
additional information on prompts. 

USAGE 

declare ssu_$set_prompt_mode entry (ptr, bit (*) ) ; 
call ssu_$set_prompt_mode (sci_ptr, prompt_mode) ; 
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ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

prompt_mode 

is the new prompt mode. (Input) The individual bits are interpreted as follows: 

bit 1 ON suppress all prompts. 

bit 2 ON prompt after blank request lines. 

bit 3 ON suppress prompts if there is type ahead. 

There are named constants in the ssu_prompt_modes.incl.pll include file that can 
be used to create this value. 



Entry: ssu $set ready mode 

This entry is used to turn ready message processing in the subsystem listener on or 
off. See the description of interactive subsystem request loops in the Programmer's 
Reference Manual for additional information on ready messages. 

USAGE 

declare ssu_$set_ready_mode entry (ptr, bit(l) aligned); 
call ssu_$set_ready_mode (sci_ptr, enable_sw); 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

enable_sw 

is a bit indicating whether or not ready processing is to be enabled. (Input) If it 
is "l"b, ready processing will be performed; if it is "0"b, ready processing will 
not be performed. 
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Entry: ssu $set request processor options 

This entrypoint changes the request processor options presently in effect for the 
current subsystem. 

USAGE 

declare ssu_$set_request_processor_options entry (ptr, ptr, 
fixed bin (35)) ; 

call ssu_$set_request_processor_opt ions (sci_ptr, rp_opt i ons_ptr , code); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

rp_options_ptr 

is a pointer to the rp_opiions structure containing the new request processor 
options for this subsystem. (Input) The rp_options structure is defined in the 
system include file ssu_rp_options.incl.pll. 

code 

is a standard system status code. (Output) It can have one of the following 

values: 

0 

the requested options have been accepted and are now in effect for this 

subsytem. 
error_table_$unimplemented_version 

the version of the supplied rp_options structure is not RP_OPTIONS_VERSION_l. 
error_table_$bad_subr_arg 

a value other than one of the named constants in the system include file 

cp_character_types.incl.pll was used in the new request language. 
error_table_$unbalanced_brackets 

the new request language defined in the rp_options structure contains a 

character defined as a begin or end active string and no matching end or 

begin active string exists in the language. 
error_table_$unbalanced_paren theses 

the new request language defined in the rp_options structure contains a 

character defined as a begin or end iteration set and no matching end or 

begin iteration set exists in the language. 

NOTES 

See the information on the subsystem request language in the Programmer's Reference 
Manual for a description of the rp_options structure and the request processor options 
mechanism. 
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This is a replaceable procedure. See the Programmer's Reference Manual for 
information on the use of replaceable procedures within interactive subsystems. 



Entry: ssu Sset request tables 

This entry is used to set the list of request tables searched by this subsystem 
invocation. See the Programmer's Reference Manual for additional information on the 
use of interactive subsystem request tables. 

USAGE 

declare ssu_$set_request_tables entry (ptr, ptr, fixed bin(35)); 
call ssu_$set_request_tabl es (sci_ptr, rtl_ptr, code); 
ARGUMENTS 
sci_ptr 

is a pointer to the subsystem control structure for this invocation as returned by 
ssu_$create_invocation. (Input) 

rtl_ptr 

is a pointer to the request_tables_list structure which is the new list of request 
tables for this subsystem invocation; this structure is described in detail in the 
writeup of ssu_$list_request_tables, above. The table_valid elements of the caller's 
structure are set appropriately by this call. (Input) 

code 

is a standard system status code. (Output) 
0 

the supplied request tables list was accepted. 
error_table_$unimplemented_version 

the supplied version of the request_tables_list structure is not supported by 

this entry. 
ssu_et_$invalid_request_table 

one or more of the request tables in the list are not valid; the invalid 

request tables are marked by the table_valid bits in the caller's structure. 

NOTES 

Each supplied request table is validated as described above in the description of 
ssu_$add_request_table. This entry also fills in the values of table_valid field of the 
supplied request_tables_list structure. 

If all the request tables are valid, the current list is replaced with the newly supplied 
list and a zero status code is returned. 
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Entry: ssu Sstandalone invocation 

This entry creates a "standalone" subsystem invocation for use by Multics commands /active 
functions which can also be used as subsytem requests. Additional information on the 
use of Multics commands as subsystem requests is provided in the Programmer's 
Reference Manual. 

USAGE 

declare ssu_$standalone_i nvocat ion entry (ptr, char (*) , char («) , ptr, 
entry, fixed bin(35)); 

call ssu_$standalone_i nvocat ion (sci_ptr, comma nd_name, command_version, 
arg_l i st_ptr , abort_entry, code); 

ARGUMENTS 

sci_ptr 

is a pointer to the subsystem control information created for this standalone 
invocation. (Output) 

command_name 

is the name of the Multics command /active function on whose behalf the 
standalone invocation is created. (Input) This name is printed in the message 
produced by calls to ssu_$print_message, ssu_$abort_line, and ssu_$abort_subsystem. 

command_version 

is the current version of this command /active function. (Input) 

arg_list_ptr 

is a pointer to the command's argument list. (Input) If a null pointer is supplied, 
the subsystem will use the argument list of the caller of ssu_$standalone_invocation. 
This argument list can be examined by calls to ssu_$arg_ptr, ssu_$return_arg, and 
ssu_$arg_count. 

abort_entry 

is a procedure of no arguments which will be invoked by ssu_$abort_line and 
ssu_$abort_subsystem after the error message, if any, has been printed. (Input) 

code 

is a system status code. (Output) 
NOTES 

Calls to ssu_$execute_line and ssu_$evaluate_active_string within a standalone invocation 
are translated into calls to cu_$cp and cu_$evalaute_active_string, respectively. 
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Calls to ssu_$print_message, ssu_$abort_line and ssu_$abort_subsystem within a standalone 
invocation are translated into calls to com_err_ or active_fnc_err_ depending on 
whether the program which created the invocation was invoked as a Multics command 
or as a Multics active function. In addition, after the error message is printed, 
ssu_$abort_line and ssu_$abor t_s ubsy stem will invoke the abort_entry supplied when the 
subsystem invocation was created. This entry will normally perform a non-local goto 
back to a label in the command's main procedure so that it can clean up and return 
to its caller. 



Name: stu 

The stu_ (symbol table utility) subroutine provides a number of entry points for 
retrieving information from the runtime symbol table section of an object segment 
generated by the PL/ 1, FORTRAN, or COBOL compilers. A runtime symbol table is 
produced when a program is compiled with the -table control argument or when a 
runtime symbol table is required to support a feature of the language such as PL/ 1 
data-directed or FORTRAN NAMELIST input/output statements. A partial symbol 
table, containing only a statement map, is produced when a program is compiled with 
the -brief _table control argument 



Entry: stu $decode runtime value 

This entry point is called to decode encoded values (e.g., string length or arithmetic 
precision) stored in a runtime_symbol node. 

USAGE 

declare stu_$decode_runt ime_val ue entry (fixed bin(35)» ptr, ptr, ptr, 
ptr, ptr, fixed bin) returns (fixed bin (35)); 

value = stu_$decode_runt ime_value (v, block_ptr, stack_ptr, link_ptr, 
text_ptr, ref_ptr, code); 

ARGUMENTS 

v 

is an encoded value from" a runtime_symbol node, e.g., runtime_symbol.size. 
(Input) 

block_ptr 

points to the runtime_block node that corresponds to the block that contains the 
declaration of the identifier whose runtime_symbol node contains the encoded 
value. Normally, the value of block_ptr is obtained from a call to the 
stu_$find_runtime_symbol entry point described below. (Input) 
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stack_ptr 

is a pointer to the active stack frame associated with the procedure or begin 
block that corresponds to the specified runtime_block node. If the specified block 
node is quick, stack_ptr should point to the stack frame in which the quick block 
is placing its automatic storage. If the specified block is not active and does not 
have a current stack frame, stack_ptr can be null. (Input) 

link_ptr 

is a pointer to the linkage section of the specified block. If link_ptr is null, the 
stu_$decode_runtime_value entry point attempts to obtain the linkage pointer, if it 
is needed, from the linkage offset table (LOT); decoding fails if a pointer to the 
linkage section is needed and text_ptr, block_ptr, and link_ptr are all null or if 
the segment has never been executed. (Input) 

text_ptr 

is a pointer to the base of the object segment that contains the specified block. 
If text_ptr is null, the stu_$decode_runtime_value entry point attempts to obtain 
the text pointer, if it is needed, from the active stack frame or the block_ptr; 
decoding fails if a pointer to the object segment is needed and stack_ptr, 
block_ptr, and tcxt_ptr are all null. (Input) 

ref_ptr 

is the value of the pointer to be used as locator qualifier if the variable that 
corresponds to the runtime_symbol node that contains the encoded value is based. 
The value of ref_ptr can often be determined by means of the 
stu_$get_implicit_qualifier entry point described below. (Input) 

code 

is a status code. (Output) It can be: 

0 if the encoded value was successfully decoded. 

1 if the value could not be decoded. 

value 

is the decoded value if the value of code is 0- (Output) 



Entry: stu Sdecode runtime value extended 

This entry point is called to decode encoded values (e.g„ string length or arithmetic 
precision) stored in a runtime_symbol node. 

USAGE 

declare stu_$decode_runtime_value entry (fixed bin(35)» ptr, ptr, ptr, 
ptr, ptr, fixed bin) returns (fixed bin (35)); 

value = stu_$decode_runt i me_va 1 ue (v, b!ock_ptr , stack_ptr, !in!<_ptr s 
text_ptr, ref_ptr, code); 



2-810 



AG93-05 



ARGUMENTS 



v 

is an encoded value from a runtime_symbol node, e.g., runtime_symbol.size. 
(Input) 

block_ptr 

points to the runtime_block node that corresponds to the block that contains the 
declaration of the identifier whose runtime_symbol node contains the encoded 
value. Normally, the value of block_ptr is obtained from a call to the 
stu_$find_runtime_symbol entry point described below. (Input) 

stack_ptr 

is a pointer to the active stack frame associated with the procedure or begin 
block that corresponds to the specified runtime_block node. If the specified block 
node is quick, stack_ptr should point to the stack frame in which the quick block 
is placing its automatic storage. If the specified block is not active and does not 
have a current stack frame, stack_ptr can be null. (Input) 

link_ptr 

is a pointer to the linkage section of the specified block. If link_ptr is null, the 
stu_$decode_runtime_value entry point attempts to obtain the linkage pointer, if it 
is needed, from the linkage offset table (LOT); decoding fails if a pointer to the 
linkage section is needed and text_ptr, block_ptr, and link_ptr are all null or if 
the segment has never been executed. (Input) 

text_ptr 

is a pointer to the base of the object segment that contains the specified block. 
If text_ptr is null, the stu_$decode_runtime_value entry point attempts to obtain 
the text pointer, if it is needed, from the active stack frame or the block_ptr; 
decoding fails if a pointer to the object segment is needed and stack_ptr, 
block_ptr, and text_ptr are all null. (Input) 

ref_ptr 

is the value of the pointer to be used as locator qualifier if the variable that 
corresponds to the runtime_symbol node that contains the encoded value is based. 
The value of ref_ptr can often be determined by means of the 
stu_$get_implicit_qualifier entry point described below. (Input) 

code 

is a status code. (Output) It can be: 

0 if the encoded value was successfully decoded. 

1 if the value could not be decoded. 

value 

is the decoded value if the value of code is 0. (Output) 
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Entry: stu__$find_block 

This entry point, given a pointer to the symbol table header of an object segment, 
searches the runtime symbol table of the object segment for the runtime_block node 
that corresponds to a given procedure block in the object program. 

USAGE 

declare stu_$f i nd_b1ock entry (ptr, char (*) aligned) returns (ptr) ; 

block_ptr = stu_$f i nd_bl ock (header_ptr, name) 

ARGUMENTS 

header_ptr 

points to a symbol table header. (Input) 

name 

is the ASCII name of the runtime_block node to be found. The name of a 

runtime_block node is the same as the first name written on the procedure 

statement that corresponds to the runtime_block node. (Input) 

block_ptr 

is set to point to the runtime_block node if it is found or is null if the block is 
not found. (Output) 



Entry: stu Sfind containing block 

This entry point, given a pointer to the symbol table header of a standard object 
segment and an offset into the text section, returns a pointer to the runtime_block 
node corresponding to the smallest procedure or begin block that lexically contains the 
source line for the instuction pointed to, or null if none could be found. 

USAGE 

declare stu_$f i nd_conta i n i ng_bl ock entry (ptr, fixed b i n ( 1 8) unsigned) 
returns (ptr) ; 

bp = stu_$f ind_containing_block (hp, offset); 

ARGUMENTS 

hp 

is a pointer to the symbol table header. (Input) 
offset 

is the offset from the base of the segment of an instruction. (Input) 
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bp 

is the returned pointer to the runtime_block node, or null. 



Entry: stu_$find header 

This entry point, given an ASCII name and/or a pointer to any location in a (possibly 
bound) object segment, searches the given segment for the symbol table header 
corresponding to the designated program. 

USAGE 

declare stu_$f i nd_header entry (ptr, char (32) aligned, fixed bin (24)) 
returns (ptr) ; 

header_ptr = stu_$f i nd_header (seg_ptr, name, be); 

ARGUMENTS 

seg_ptr 

points to any location in the object segment (Input) 
name 

is the ASCII name of the program whose symbol header is to be found. If 
seg_ptr is null, name is treated as a reference name and the segment is 
determined according to the user's search rules. If the designated segment is 
bound, name specifies the component. (Input) 

be 

is the bit count of the object segment; if 0, the stu_$find_header entry point 
determines the bit count itself. (Input) 

header_ptr 

points to the symbol table header if it is found or is null if the header is not 
found. (Output) 

NOTES 

Since determining the bit count of a segment is relatively expensive, the user should 
provide the bit count if he has it available (e.g., as a result of a call to 
hcs_$initiate_count). 
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Entry; stu_$find runtime symbol 

This entry point, given a pointer to the runtime__block node that corresponds to a 
procedure or begin block, searches for the runtime_symbol node that corresponds to a 
specified identifier name. If the name is not found in the given block, the parent 
block is searched. This is repeated until the name is found or the root block of the 
symbol structure is reached, in which case a null pointer is returned. 

USAGE 

declare stu_$f i nd_runt ime_symbol entry (ptr, char (*) aligned, ptr, 
fixed bin) returns (ptr); 

symbol_ptr = stu_$f i nd_symbol (block_ptr, name, found_ptr, steps); 

ARGUMENTS 

block_ptr 

points to the runtime_block node in which the search is to begin. (Input) 
name 

is the ASCII name of the runtime_symbol node to be found. A name can be a 
fully or partially qualified structure name (e.g., "a.b.c"), in which the runtime_symbol 
node that corresponds to the lowest level item is located. (Input) 

found_ptr 

is set to point to the runtime_block node in which the specified identifier is 
found. (Output) 

steps 

is set to the number of steps that must be taken along the pll_stack_frame.display_ptr 
chain to locate the stack_frame associated with the block designated by found_ptr 
starting at the stack frame for the block designated by block_ptr. (See "Example" 
below.) If the given identifier is found in the specified block, the value of steps 
is 0. (Output) 

If the search fails, the value of steps indicates the reason for the failure as 
follows: 

-1 block_ptr is null 

-2 more than 64 structure levels 

-3 name too long 

-4 no declaration found 

-5 symbol reference is ambiguous 

symbol_ptr 

is set to point to the runtime_symbol node if it is found or is null if an error 
occurs. (Output) 
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Entry: stu $get block 

Given a pointer to the stack frame, gets a pointer to the runtime_block for the entry 
that created the frame and to the header for the object segment- This entry point is 
equivalent to stu_$get_runtime_block except that the location is determined by the 
information in the stack frame. 

USAGE 

declare stu_$get_block entry (ptr, ptr, ptr) ; 
call stu_$get_block (sp, hp, bp); 
ARGUMENTS 
sp 

points to the stack frame in question. (Input) 

hp 

points to the header for the runtime symbol table of the object segment that 
contains the entry that created the frame. If is set to null if the object segment 
has no symbol table, or if the object segment cannot be interpreted. (Output) 

bp 

points to the runtime_block node for the entry that created the frame. It is set 
to null if the object segment has no symbol table or could not be interpreted. 



Entry: stu Sget implicit qualifier 

This entry point, given a pointer to the symbol node that corresponds to a PL/ 1 
based variable, attempts to return the value of the pointer variable that appeared in 
the based declaration (e.g., the value of "p" in "del a based (p);"). A null pointer is 
returned if the declaration does not have the proper form or if the value of the 
pointer cannot be determined. 

USAGE 

declare stu_$get_imp1 i c i t_qual i f i er entry (ptr, ptr, ptr, ptr, ptr) 
returns (ptr) ; 

ref_ptr = stu_$get_i mpl ici t_qual i f ier (hlock_ptr, symbo!_ptr , stack_ptr, 
link_ptr, text_ptr) ; 
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ARGUMENTS 



block_ptr 

points to the mntime_block node that corresponds to the procedure or begin 
block in which the based variable is declared. (Input) 

symbol_ptr 

points to the runtime_symbol node that corresponds to the based variable. (Input) 
stack_ptr 

is a pointer to the active stack frame associated with the block in which the 
based variable is declared. If the specified block node is quick, stack_ptr should 
point to the stack frame in which the quick block is placing its automatic storage. 
If the specified block is not active and does not have a current stack frame, 
stack_ptr can be null. (Input) 

link_ptr 

is a pointer to the linkage section of the specified block. If link_ptr is null, the 
stu_$get_implicit_qualifier entry point attempts to obtain the linkage pointer, if it 
is needed, from the active stack frame; the implicit qualifier cannot be 
determined if a pointer to the linkage section is needed and stack_ptr and 
link_ptr are both null. (Input) 

text_ptr 

is a pointer to the base of the object segment that contains the specified block. 
If text_ptr is null, the stu_$get_implicit_qualifier entry point attempts to obtain 
the text pointer, if it is needed, from the active stack frame; the implicit 
qualifier cannot be determined if a pointer to the object section is needed and 
stack_ptr and text_ptr are both null. (Input) 

ref_ptr 

is set to the value of the implicit qualifier or is null if the value cannot be 
determined. (Output) 

NOTES 

A null pointer is returned for any one of a number of reasons. Some of these are: 
The based variable was declared without an implicit qualifier, e.g., 
del a based; 

Determining the implicit qualifier involves evaluating an expression, for example, the 
based variable was declared as: 

del a based (p (i) ) ; 

The based variable was declared with an implicit qualifier, but it is not possible to 

obtain the address of the qualifier (e.g., it is an authentic pointer, and stack_ptr is 

null). 
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Entry: stu $get line 

This entry point, given a pointer to the symbol header of a standard object segment 
and an offset in the text section of the object segment, returns information that 
allows the source line that generated the specified location to be accessed. This entry 
point can be used with programs that have only a partial runtime symbol table. 

USAGE 

declare stu_$get_l i ne entry (ptr, fixed b i n ( 1 8) , fixed bin, 
fixed bin (18), fixed bin(l8), fixed bin, fixed bin); 

call stu_$get_l i ne (head_ptr, offset, n_stms, line_no, line_offset, 
1 ine__length, file); 

ARGUMENTS 

head_ptr 

is a pointer to the symbol section header of a standard object segment. (Input) 
offset 

is the offset of an instruction in the text section. (Input) 
n_stms 

indicates the number of source statements about which information is desired; the 
string specified by file, line_offset, and line_length is the source for n_stms 
statements, starting with the statement that contains the given instruction. (Input) 

line_no 

is set to the line number, in the file in which it is contained, of the statement 
that contains the specified instruction or is -1 if the given offset does not 
correspond to a statement in the object program. (Output) 

line_offset 

is set to the number of characters that precede the first character of the source 
for the specified statement. (Output) 

line_length 

is set to the number of characters occupied by the n_stms statements that start 
with the statement that contains the specified location; the source for these 
statements is assumed to be entirely contained within a single source file. Let S 
be the contents of the source file that contains the specified statements considered 
as a single string; then the source string for the n_stms statements is 
substr(S,line_of f set+l,line_length). (Output) 

file 

is the number of the source file in which the source for the desired statements is 
contained. (Output) 
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Entry: stu $get_line no 

This entry point, given a pointer to a runtime_block node and an offset in the text 
segment that corresponds to the block, determines the line number, starting location, 
and number of words in the source statement that contains the specified location. 

USAGE 

declare stu_$get_l i ne_no entry (ptr, fixed bin(l8), fixed bin(l8), 
fixed bin (18)) returns (f i xed bin (18) ) ; 

line_no = s tu_$get_l i ne_no (block_ptr, offset, start, num); 

ARGUMENTS 

block_ptr 

points to the runtime_block node that corresponds to the block in which the 
instruction offset exists. (Input) 

offset 

is the offset of an instruction in the text segment (Input) 

start 

is set to the offset in the text segment of the first instruction generated for the 
source line that contains the specified instruction or is -1 if the line is not 
found. (Output) 

num 

is set to the number of words generated for the specified source line. (Output) 
line_no 

is set to the line number, in the main source file, of the statement that contains 
the specified instruction or is -1 if the specified offset does not correspond to a 
statement m the program. (Output) 

NOTES 

All line numbers refer to the main source file and not to files accessed by means of 
the %include statement. 

No distinction is made between several statements that occur on the same source line. 
The start argument is the starting location of the code generated for the first 
statement on the line and num is the total length of all the statements on the line. 
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Entry: stu Sget location 

This entry point, given a pointer to a runtime_block node and the line number of a 
source statement in the block, returns the location in the text segment of the first 
instruction generated by the specified source line. 

USAGE 

declare stu_$get_locat ion entry (ptr, fixed b i n (1 8) ) returns 
(fixed bin(l8)) ; 

offset = stu_$get_locat i on (block_ptr, line_no); 

ARGUMENTS 

block_ptr 

points to the runtime_block node. (Input) 
line_no 

specifies the source line number, which must be in the main source file. (Input) 
offset 

is set to the offset in the text segment of the first instruction generated for the 
given line or is -1 if no instructions are generated for the given line. (Output) 



Entry: stu Sget map index 

This entry point, given a pointer to the symbol header of a standard object segment 
and an offset into the text section, returns the index of the statement map entry for 
the source line that generated the instruction at the offset and a pointer to the map 
entry. This entry can be used with object segments that have only a partial runtime 
symbol table. 

USAGE 

declare stu_$get_map_i ndex entry (ptr, fixed bin(l8) unsigned, 
f i xed bin, ptr) ; 

call stu_$get_map_i ndex (header, offset, map_index, map_entry_ptr) ; 

ARGUMENTS 

header 

is a pointer to the symbol header for the object segment. (Input) 
offset 

is the offset of an instruction, relative to the base of the segment. (Input) 
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map„index 

is the index in the statement map array of the statement map entry for the line 
corresponding to the instruction, or -1 if no such map entry could be found. 
(Output) 

map_entry_ptr 

is a pointer to the map entry identified by map_index, or null if no such entry 
could be found. (Output) 

NOTES 

Even though the map entry index and map entry pointer can be computed from each 
other, both are supplied to the user for convenience. 



Entry: stu $get runtime address 



This entry point, given a pointer to a runtime_symbol node and information about the 
current environment of the block in which the symbol that corresponds to the 
runlirne_symboi node is declared, determines the address of the specified variable. 



USAGE 



declare stu_$get_runt i me_address entry (ptr, ptr, ptr, ptr, ptr, ptr, 
ptr) returns (ptr) ; 

add_ptr = stu_$get_runt ime_address (block_ptr, symbol_ptr, stack_ptr, 
link_ptr, text_ptr, ref_ptr, subs_ptr) ; 



ARGUMENTS 



block_ptr 

points to the runtime_block node that corresponds to the block in which the 
symbol, whose address is to be determined, is declared. (Input) 



symbol_ptr 

points to the runtime_symbol node that corresponds to the symbol whose address 
is to be determined. (Input) 

stack_ptr 

is a pointer to the active stack frame associated with the procedure or begin 
block that corresponds to the specified runtime_block node. If the specified block 
is quick, stack_ptr should point to the stack frame in which the quick block is 
placing its automatic storage. If the specified block is not active and does not 
have a current stack frame, stack_ptr can be null. (Input) 



2-820 



AG93-05 



iink_ptr 

is a pointer to the linkage section of the specified block. If link_ptr is null, the 
stu_$get_runtime_address entry point attempts to obtain the linkage pointer, if it 
is needed, from the LOT; the address of the specified symbol cannot be 
determined if a pointer to the linkage section is needed and text_ptr, block_ptr, 
and link_ptr are all null or the segment has never been executed. (Input) 

text_ptr 

is a pointer to the base of the object segment that contains the specified block. 
If text_ptr is null, the stu_$get_runtime_address entry point attempts to obtain the 
text pointer, if it is needed, from the active stack frame or the block_ptr; the 
address of the specified symbol cannot be determined if a pointer to the object 
segment is needed and stack_ptr, block_ptr, and text_ptr are all null. (Input) 

ref_ptr 

is the value of the reference pointer to be used if the runtime_symbol node 
corresponds to a based variable. If ref_ptr is null, the stu_$get_runtime_address 
entry point calls the stu_$get_implicit_qualifier entry point (described above) to 
determine the value of the pointer that was used in the declaration of the based 
variable. (Input) 

subs_ptr 

points to a vector of single-precision fixed -point binary subscripts. The number 
of subscripts is assumed to match the number required by the declaration. This 
argument can be null if the runtime_symbol node does not correspond to an 
array. (Input) 

add_ptr 

is set to the full bit address (with full bit offset) of the variable that corresponds 
to the symbol node or is null if the address cannot be determined. (Output) 



Entry: stu $get runtime block 

This entry point, given a pointer to an active stack frame and a location within the 
object segment that created the frame, returns pointers to the symbol table header of 
the object segment and the runtime_block node that corresponds to the procedure or 
begin block associated with the stack frame. Null pointers are returned if the stack 
frame does not belong to a PL/ 1, FORTRAN, or COBOL program or if the object 
segment does not have a runtime symbol table. 

USAGE 

declare stu_$get_runt ime_b 1 ock entry (ptr, ptr, ptr, fixed b i n (1 8) ) ; 
call stu_$get_runt ime_bl ock (stack_ptr, header_ptr, block_ptr, loc) ; 
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ARGUMENTS 



stack_ptr 

points to an active stack frame. (Input) 
header_ptr 

is set to point to the symbol table header or is null if the object segment does 
not have a runtime symbol table. (Output) 

block_ptr 

is set to point to the runtime_block node that corresponds to the procedure or 
begin block associated with the stack frame or is null if the object segment does 
not have a runtime symbol table. (Output) 

loc 

is an address within the object segment (e.g., where execution was interrupted); a 
negative value for loc means no location information is specified. The additional 
information provided by loc enables the stu_$get_runtime_block entry point to 
return the runtime_block node that corresponds to the quick PL/ 1 procedure or 
begin block that is sharing the designated slack frame and was active at the time 
execution was interrupted. (Input) 



Entry: stu $get runtime line no 

This entry point, given a pointer to the symbol header of a standard object segment 
and an offset in the text section of the object segment, returns information about the 
line that caused the specified instruction to be generated. Since the symbol header is 
used to locate the statement map, this entry point can be used with object segments 
that have only a partial runtime symbol table. 

USAGE 

dec ] 3T£ stu $ cj s t runtime 1 i rse no entry (ptr, fixed bln(l8) , 
f i xed~b i n (T8) , fixed bin(l8), fixed bin(l8)); 

call stu_$get_runt ime_l i ne_no (head_ptr, offset, start, num. 1 i ne_no) ; 

ARGUMENTS 

head_ptr 

is a pointer to the symbol section header of a standard object segment. (Input) 
offset 

is the offset of an instruction in the text section. (Input) 

start 

is set to the offset in the text segment of the first instruction generated for the 
source line that contains the specified instruction or is -1 if the line is not 
found. (Output) 
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num 

is set to the number of words in the object code generated for the specified 
source line. (Output) 

line_no 

is set to the line number, in the main source file, of the statement that contains 
the specified instruction or is -1 if the specified offset does not correspond to a 
statement in the program. (Output) 

NOTES 

All line numbers refer to the main source file and not to files accessed by means of 
the %include statement. 

No distinction is made between several statements that occur on the same source line. 
The start argument is the starting location of the code generated for the first 
statement on the line and num is the total length of all the statements on the line. 



Entry: stu $get runtime location 

This entry point, given a pointer to the symbol header of a standard object segment 
and a line number in the main source file, returns the starting location in the text 
section of the object code generated for the line. This entry point can be used with 
object segments that have only a partial runtime symbol table. 

USAGE 

declare stu_$get_runt ime_J ocat i on entry (ptr, fixed bin) returns 
(fixed bin (18) ) ; 

offset = stu_$get_runt ime_l ocat i on (head_ptr, 1 i ne_no) ; 

ARGUMENTS 

head_ptr 

is a pointer to the symbol section header of a standard object segment (Input) 
line_no 

is the line number of a statement in the main source file. (Input) 
offset 

is set to the location in the text segment where the object code generated for the 
specified line begins or is -1 if no code is generated for the given line. (Output) 



2-823 



AG93-05 



stu_ 



Entry: stu $get statement map 

This entry point, given a pointer to the symbol header of a standard object segment, 
returns information about the statement map of the object segment. This entry point 
can be used with object segments that have only a partial runtime symbol table. 

USAGE 

declare stu_$get_statement_map entry (ptr, ptr, ptr, fixed bin); 

call stu_$get_statement_map (head_ptr, first_ptr, last_ptr, map_size); 

ARGUMENTS 

head_ptr 

is a pointer to the symbol section header of a standard object segment. (Input) 
first_ptr 

is set to point to the first entry in the statement map of the object segment or 
is null if the object segment does not have a statement map. (Output) 

last_ptr 

is set to point to the location following the last entry in the statement map of 
the object segment or is null if the object segment does not have a statement 
map. (Output) 

map_size 

is set to the number of words in an entry in the statement map. (Output) 



Entry: stu Soffset to pointer 

This entry point attempts to convert an offset variable to a pointer value using the 
area, if any, on which the offset was declared. 

USAGE 

declare stu_$of f set_to_poi nter entry (ptr, ptr, ptr, ptr, ptr, ptr) 
returns (ptr) ; 

off_ptr = stu_$of f set_to_poi nter (block_ptr, symbol_ptr, data_ptr, 
stack_ptr, link_ptr, text_ptr) ; 
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ARGUMENTS 



block_ptr 

points to the runtime_block node that corresponds to the procedure or begin 
block in which the offset variable is declared. (Input) 

symbol_ptr 

points to the runtime_symbol node that corresponds to the offset variable. (Input) 
data_ptr 

points to the offset value to be converted to a pointer. (Input) 
stack_ptr 

is a pointer to the active stack frame associated with the block in which the 
offset variable is declared. If the specified block node is quick, stack_ptr should 
point to the stack frame in which the quick block is placing its automatic storage. 
If the specified block is not active and does not have a current stack frame, 
stack_ptr can be null. (Input) 

link_ptr 

is a pointer to the linkage section of the specified block. If link_ptr is null, the 
stu_$offset_to_pointer entry point attempts to obtain the linkage pointer, if it is 
needed, from the stack frame; eon version fails if a pointer to the linkage section 
is needed and stack_ptr and link_ptr are both null. (Input) 

text_ptr 

is a pointer to the base of the object segment that contains the specified block. 
If text_ptr is null, the stu_$offset_to_pointer entry point attempts to obtain the 
text pointer, if it is needed, from the active stack frame; conversion fails if a 
pointer to the text section is needed and stack_ptr and link_ptr are both null. 
(Input) 

off_ptr 

is set to the pointer value that corresponds to the offset value; it is null if the 
conversion fails or if the offset value is itself null. (Output) 



Entry: stu Spointer to offset 

This entry point attempts to convert a pointer value to an offset variable using the 
area, if any, on which the offset was declared. 

USAGE 

declare stu_$poi nter_to_of f set entry (ptr, ptr, ptr, ptr, ptr, ptr) 
returns (offset) ; 

off_val = stu_$poi nter_to_of f set (block_ptr, symbol_ptr, data_ptr, 
stack_ptr, link_ptr, text_ptr) ; 
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ARGUMENTS 



block_ptr 

points to the runtime_block node that corresponds to the procedure or begin 
block in which the offset variable is declared. (Input) 

symbol_ptr 

points to the runtime_symbol node that corresponds to the offset variable. (Input) 
data_ptr 

points at the pointer value to be converted to an offset. This pointer value must 
be an unpacked pointer value. (Input) 

stack_ptr 

is a pointer to the active stack frame associated with the block in which the 
offset variable is declared. If the specified block node is quick, stack_ptr should 
point to the stack frame in which the quick block is placing its automatic storage. 
If the specified block is not active and does not have a current stack frame, 
stack_ptr can be null. (Input) 

link_ptr 

is a pointer to the linkage section of the specified block. If link_ptr is null, the 
stu_$offset_to_pointer entry point attempts to obtain the linkage pointer, if it is 
needed, from the stack frame; conversion fails if a pointer to the linkage section 
is needed and stack_ptr and link_ptr are both null. (Input) 

text_ptr 

is a pointer to the base of the object segment that contains the specified block. 
If text_ptr is null, the stu_$offset_to_pointer entry point attempts to obtain the 
text pointer, if it is needed, from the active stack frame; conversion fails if a 
pointer to the text section is needed and stack_ptr and link_ptr are both null. 
(Input) 

off val 

is set to the offset value that corresponds to the pointer value; it is null if the 
conversion fails or if the pointer value is itself null. (Output) 



Entry: stu $remote format 

This entry point decodes a remote format specification. 
USAGE 

declare stu_$remote_f ormat entry (fixed bin(35)» ptr, ptr, label) 
returns (f i xed bin); 

code = stu__$remote_f ormat (value, stack_ptr, ref_ptr, format); 
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ARGUMENTS 
value 

is the remote format value to be decoded. (Input) 
stack_ptr 

is a pointer to the active stack frame of the block that contains the format being 
decoded. (Input) 

ref_ptr 

is the pointer value to be used if the format value being decoded requires pointer 
qualification. (Input) 

format 

is set to the format value if decoding is successful. (Output) 

code 

is a status code. (Output) It can be: 

0 if decoding is successful. 

1 if decoding is not successful. 

EXAMPLES 

The use of some of the entry points documented above is illustrated by the following 
sample program, which is called with: 

stack_ptr 

a pointer to the stack frame of a PL/I block, 
symbol 

an ASCII string giving the name of a user symbol in the PL/ 1 program. 
subs_ptr 

a pointer to an array of binary integers that give subscript values. 
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The procedure determines the address and size of the specified symbol If any errors 
occur, the returned address is null. 

example: proc (stack_ptr, symbol, subs_ptr, size) returns (ptr) ; 

declare stack_ptr ptr, 

symbol char (*) aligned, 

subs_ptr ptr, 

s i ze f i xed b i n (35) ; 

declare (header_ptr, block_ptr, symbol_ptr, ref_ptr, sp, blk_ptr, 
stack_ptr, add_ptr) ptr, 
(i , steps) f i xed bi n, 
code f i xed b i n (35) • 

stu_$get_runtime_block entry (ptr, ptr, ptr, fixed b i n ( 1 8) ) , 
stu_$f i nd_runt ime_symbol entry (ptr, char (*) aligned, ptr, 

fixed bin) returns (ptr) , 
stu_$get_runt ime_address entry (ptr, ptr, ptr, ptr, ptr, ptr, 

ptr) returns (ptr) , 
5 tu_$decode_runt i me_va 1 ue entry (fixed bin(35)» ptr, ptr, ptr, 

ptr, ptr, fixed bin) returns (f i xed bin(35))» 

^include p 1 l_stack_f rame; 
% include runt ime_symbol ; 

/« determine header and block pointers */ 

call stu_$get_runt i me_b 1 ock (stack_ptr, header_ptr, 

block_ptr , -1) ; 
if block_ptr = null then return (nul 1 ) ; 

/* search for specified symbol */ 

symbo 1 _pt r = stu_$f i nd_runtirns_syrr.be] (blcck_ptr, symbol, 
b 1 k_ptr , steps) ; 
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if symboi_ptr = null then return (null); 

/* determine stack frame of block owning symbol «/ 

sp = stack_ptr; 
do i a 1 to steps; 

sp = sp -> pi l_stack_f rame.di splay__ptr ; 

end; 

/* determine address of symbol */ 
ref_ptr = nul 1 ; 

add_ptr = stu_$get_runt ime_address (blk_ptr, symbol_ptr, sp, 
null, null, ref_ptr, subs_ptr) ; 

if add_ptr = null then return (nul 1) ; 

/* determine size */ 

size = symbol_ptr -> runt ime_symbol . s i ze; 

if s i ze < 0 
then do; 

size = stu_$decode_runtime_value (size, blk_ptr, sp, null, 

null, ref_ptr, code); 
if code ~= 0 then return (nu 1 1 ) ; 
end ; 

return (add_ptr) ; 
end example; 
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Name: sub err 

The sub_err_ subroutine is called by other programs that wish to report an unexpected 
situation without usurping the calling environment's responsibility for the content of 
and disposition of the error message and the choice of what to do next. The caller 
specifies an identifying message and may specify a status code. Switches that describe 
whether and how to continue execution and. a pointer to further information may also 
be passed to this subroutine. The environment that invoked the subroutine caller of 
sub_err_ may intercept and modify the standard system action taken when this 
subroutine is called. 

General purpose subsystems or subroutines, which can be called in a variety of I/O 
and error handling environments, should report the errors they detect by calling the 
sub_err_ subroutine. 

USAGE 

declare sub_err_ entry options (variable); 

call sub_err_ (code, name, flags, info_ptr, retval, ctl_string, 
ioa_args) ; 

ARGUMENTS 

code 

is a standard status code describing the reason for calling the sub_err_ subroutine. 
(It is normally declared fixed bin(35); but it can be any computational data type. 
If not fixed bin(35), it will be converted to fixed bin(35)). (Input) 

name 

is the name (declared as a nonvarying character string) of the subsystem or 
module on whose behalf the sub_err_ subroutine is called. (Input) 

flags 

describe options associated with the error. The flags argument should be declared 
as a nonvarying bit string. The following values, located in the include file 
sub_err_flags.incl.pll, are permitted: (Input) 

ACT I ON_CAN_RESTART init (""b) , 

ACT I ON__CANT_RESTART init ("l"b) , 

ACTI ON_DEFAULT_RESTART init ("OT'b) , 
ACT I 0N_QU I ET_RE START init ("OOT'b) 

ACTION_SUPPORT_SIGNAL init ("OOOT'b)) bit (36) aligned 

internal static options (constant); 

Each bit corresponds to one of the action flags in the standard condition_info_header 
structure, declared in condition_info_header.incl.pll. If multiple bits are on in the 
supplied string, all the specified flags are set. See the Programmer's Reference 
Manual for definitions of the flags. 
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info_ptr 

is a pointer (declared as an aligned pointer) to optional information specific to 
the situation. This argument is used as input to initialize info.info_ptr (see "Info 
Structure" below). The standard system environment does not use this pointer, but 
it is provided for the convenience of other environments. (Input) 

retval 

is a return value from the environment to which the error was reported. This 
argument is used as input to initialize info.retval (see "Info Structure" below). 
The standard system environment sets this value to zero. Other environments may 
set the retval argument to other values, which may be used to select recovery 
strategies. The retval argument should be declared fixed bin(35). (Input/ Output) 

ctl_string 

is an ioa_ format control string (declared as a non varying character string) that 
defines the message associated with the call to the sub_err_ subroutine. Consult 
the description of the ioa_ subroutine. (Input) 

ioa_args 

are any arguments required for conversion by the ctl_string argument. (Input) 
NOTE 

There is an obsolete calling sequence to this subroutine, in which the flags argument is 
a character string instead of a bit string. In that calling sequence, the legal values are 
"s" for ACTION_CAN_RESTART, "h" for ACTION_CANT_RESTART, "q" for 
ACTION_QUIET_RESTART, and "c" for ACTION_DEFAULT_RESTART. 

OPERATION 

The sub_err_ subroutine proceeds as follows: the structure described below is filled in 
from the arguments to the sub_err_ subroutine and the signal, subroutine is called to 
raise the sub_error_ condition. 

When the standard system environment receives a sub_error_ signal, it prints a message 
of the form: 

name error by sub_name | 1 ocat i on 

Status code message. Message from ctl_string. 

The standard environment then sets retval to zero and returns, if the value 
ACTION_DEFAULT_RESTART is specified; otherwise it calls the listener. If the start 
command is invoked, the standard environment returns to sub_err_, which returns to 
the subroutine caller of the sub_err_ subroutine unless ACTION_CANT_RESTART is 
specified. If the value ACTION_CANT_RESTART is specified, the sub_err_ subroutine 
signals the illegal_return condition. 
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HANDLER OPERATION 

All handlers for the any_other condition must either pass the sub_error_ condition on 
to another handler, or else must handle the condition correctly. Correct handling 
consists of printing the error message and of respecting the cant_restart, default_restart, 
and quiet_restart flags, unless the environment deliberately countermands these actions 
(for example, for debugging purposes). 

If an application program wishes to call a subsystem that reports errors by the 
sub_err_ subroutine and wishes to replace the standard system action for some classes 
of sub_err_ subroutine calls, the application should establish a handler for the 
sub_error_ condition by a PL /I on statement When the handler is activated as a 
result of a call to the sub_err_ subroutine by some dynamic descendant, the handler 
should call the find_condition_info_ subroutine to obtain the sub_error_info_ptr that 
points to the structure described in "Info Structure" below. 

The following is an example of how to establish a handler for the sub_error_ 
condition. 

1 on sub_error_ begin; 

2 ^include cond i t i on_i nf o; 

3 % include cond i t i on_i nf o_header ; 
h %include sub_error_i nf o; 

5 % include f ormat_document_error ; 

6 cond i t i on_i nf o_ptr = addr (local_condi t ion_i nfo) ; 

7 cond i t i on_i nfo. vers i on = cond i t i on_i nf o_vers i on_l ; 

8 call f i nd_cond i t i on_i nf o_ (null () , cond i t i on_i nf o_ptr , 

error_code) ; 

9 if error__code ~= 0 

10 then call error_rout i ne (error_code) ; 

11 sub_error_i nf o_ptr = cond i tion_i nfo. info_ptr; 

12 if sub_error_i nfo. name ~= " forma t_document_" 

13 then do; 

\k call cont i nue_to_s i gnal_ (error_code) ; 

15 return; 

16 end; 

17 f ormat_document_error_ptr = sub_error_i nfo. i nfo_ptr ; 

18 ... 

19 end; 

In the example above, line 1-4, 6-11 and 19 are the general purpose section of the 
sub_error_ on unit; lines 5 and 12-18 would change, depending upon which caller of 
sub_err_ the on unit was designed to handle (ie, format_document_ or some other 
subroutine like sort_seg_ or sort__). Line 18 of the example above represents code to 
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access the f ormat_document_error structure, analyze the information in this structure 
describing the error, take appropriate action (either stop execution of format_document_ 
by doing a nonlocal goto outside of the sub_error_ on unit, or continue execution by 
allowing the on unit's begin block to end normally). 



INFO STRUCTURE 



The structure pointed to by sub_error_info_ptr is declared as follows in the 
sub_error_info.incl.pll include file: 

del 1 sub_error_i nf o aligned based, 

2 header aligned like cond i t i on_i nf o_header , 

2 retval fixed bin (35) , 

2 name char (32) , 

2 info_ptr ptr; 

STRUCTURE ELEMENTS 



header 

is a standard header required at the beginning of each information structure 
provided to an on unit 

retval 

is the return value. The standard environment sets this value to zero. 



name 

is the name of the module encountering the condition. 
info_ptr 

is a pointer to additional information associated with the condition. 



NOTES 



The handler should check sub_error_info.name and sub_error_info.code to make sure 
that this particular call to the sub_err_ subroutine is the one desired and, if not, call 
the continue_to_signal_ subroutine. If the handler determines that it wishes to 
intercept this case of the sub_error_ condition, the information structure provides the 
message as converted, switches, etc. If control returns to the sub_err_ subroutine, any 
change made to the value of info, retval is returned to the caller of this subroutine. 
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Name: suffixed name 

This subroutine handles storage system en try names. It provides an entry point that 
creates a properly suffixed name from a user-supplied name that might or might not 
include a suffix, an entry point that changes the suffix on a user-supplied name that 
might or might not include the original suffix, and an entry point that finds a 
segment, a directory, or a multisegment file whose name matches a user-supplied name 
that might or might not include a suffix. It is intended to be used by commands that 
deal with segments with a standard suffix, but that do not require the user to supply 
the suffix in the command arguments. 



Entry: suffixed name $find 

This entry point attempts to find a directory entry whose name matches a 
user-supplied name that might or might not include a suffix. This directory entry can 
be a segment, directory, or a multisegment file. 

USAGE 

declare suf f i xed_name_$f i nd entry (char (*) , char (*) , char (*) , char (32) , 
fixed bin (2), fixed bin (5), fixed bin (35)); 

call suf f i xed_name_$f i nd (directory, name, suffix, entry, type, mode, 
code) ; 

ARGUMENTS 

directory 

is the name of the directory in which the entry is to be found. (Input) 
name 

is the name that has been supplied by the user, and that might or might not 
include a suffix. (Input) 

suffix 

is the suffix that is supposed to be part of name. It should not contain a leading 
period. (Input) 

entry 

is a version of name that includes a suffix. It is returned even if the directory 
entry does not exist. (Output) 

type 

is a switch indicating the type of directory entry that was found. (Output) 

0 no entry was found. 

1 a segment was found. 

2 a directory was found. 

3 a multisegment file was found. 
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mode 

is the caller's access mode to the directory entry that was found. See the 
hcs_$append_branch entry point for a description of mode. The caller's access 
mode to the multisegment file directory is returned for a multisegment file. 
(Output) 

code 

is a standard status code. (Output) It can be one of the following: 
error_table_$noentry 

no directory entry that matches name was found. 
error_table_$no_inf o 

no directory entry that matches name was found, and furthermore, the caller 

does not have status permission to the directory. 
error_table_$incorrect_access 

a directory entry that matches name was found, but the caller has null access 

to this entry, and to the directory containing this entry. 
error_table_$entlong 

the properly suffixed name that was made is longer than 32 characters. 



Entry: suffixed name Smake 

This entry point makes a properly suffixed name out of a name supplied by the user 
that might or might not include a suffix. 

USAGE 

declare suf f i xed_name_$make entry (char (*) , char (*) , char (32) , 
fixed bin (35)) ; 

call suf f ixed_name_$make (name, suffix, proper_name, code); 

ARGUMENTS 

name 

is the name that has been supplied by the user, and that might or might not 
include a suffix. (Input) 

suffix 

is the suffix that is supposed to be part of name. It should not contain a leading 
period. (Input) 

proper_name 

is the suffixed version of name. (Output) 

code 

is a standard status code. (Output) It can be: 
error_table_$entlong 

the properly suffixed name that was made is longer than proper_name; 
proper_name contains only a part of the properly suffixed name. 
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Entry: suffixed name^new^jsuffix 

This entry point creates a name with a new suffix by changing the (possibly existing) 
suffix on a user-supplied name to the new suffix. If there is no suffix on the 
user-supplied name, then the new suffix is merely appended to the user-supplied 
name. 

USAGE 

declare suf f i xed_name_$new_suf f i x entry (char (*) , char (*) , char (*) , 
char (32) , fixed bin (35)) ; 

call suf f i xed_name_$new_suf f i x (name, suffix, new__suffix, new_name, 
code) ; 

ARGUMENTS 

name 

is the name that has been supplied by the user, and that might or might not 
include a suffix. (Input) 

suffix 

is the suffix that might or might not already be on name. 

new_suffix 

is the new suffix. (Input) 

new_name 

is the name that was created. If name ends with .suffix, then .new_suffix replaces 
.suffix in new_name. Otherwise, new_name is formed by appending .new_suffix to 
name. (Output) 

code 



IlJ u OUU1UU1U UlUkLU WVW1W. WUIJ/UI./ J.L WUIX L/W. 



error_table_$entlong 

meaning that the suffixed new name is longer than new_name and therefore 
new_name contains only part of the suffixed new name. 

NOTES 

If error_table_$no_s_permission is encountered during the processing for 
suffixed_name_$find, it is ignored and is not returned in the status code. 
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Name: sus signal handler 

The sus_signal_handler_ subroutine is the static condition handler for the sus_ 
condition. The standard process overseers establish this handler by calling sct_manager_$set. 
For interactive processes, the sus_ condition typically occurs when the process is 
disconnected from its login terminal channel. For absentee processes, the sus_ 
condition occurs when the operators suspend the job. 

When the user reconnects to the process, sus_signal_handler_ may attempt to execute 
an exec_com, according to whether reconnect_ec_enable or reconnect_ec_disable was 
last called before disconnection. 



Entry: sus__signal handler $reconnect ec enable 

This entry point enables searching for the segment reconnect.ec when the user 
reconnects to a disconnected process. As a result, sus_signal_handler_ looks first in the 
user's home directory, then in his project directory (>user_di r_di r>Project_name) , 
and finally in >system_control_di r. When the reconnect ec segment is found, the 
command "exec_com >D i rectory_name>reconnect" is executed. 

USAGE 

declare sus_s i gnal_handler_$reconnect_ec_enable entry; 
call sus_signal_handler_$reconnect_ec_enable () ; 
NOTES 

The use of reconnect.ec is enabled automatically by the standard process overseer 
process_overseer_. 

Invocation of the reconnect.ec is not automatically enabled by the project_start_up_ 
process overseer. Thus, when using project_start_up_, the project administrator may 
enable the invocation of reconnect, ec at any point in the project_start_up.ec by using 
the reconnect_ec_enable command. 

The current command processor is used to execute the reconnect.ec command. If the 
user is using the abbrev command processor, any applicable abbreviation will be 
expanded. 
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Entry: sus signal handler ^reconnect ec disable 

This entry point reverses the effect of the sus_signal_handler_$reconnect_ec_enable 
entry. After reconnection to a disconnected process, there is no attempt made to find 
or invoke the exec_com "reconnect.ec". 

USAGE 

declare sus;_signal_hand1er_$reconnect_ec_di sable entry; 
call sus_signal_handler_$reconnect_ec_di sable () ; 



Name: sweep disk 

The sweep_disk_ subroutine walks through the subtree below a specified node of the 
directory hierarchy, calling a user-supplied subroutine once for every entry in every 
directory in the subtree. 

USAGE 

declare sweep_disk_ entry (char ( 1 68) aligned, entry); 
call sweep_disk_ (base_path, subroutine); 
ARGUMENTS 
base_path 

is the pathname of the directory that is the base node of the subtree to be 
scanned. (Input) 

subroutine 

is an entry point called for each branch or link in the subtree (see 
"User-Supplied Subroutines" below). (Input) 
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USER-SUPPLIED SUBROUTINES 

The subroutine is assumed to have the following declaration and call: 

declare subroutine entry (char(l68) aligned, char (32) aligned, 
fixed bin, char (32) ! al i gned, ptr, ptr) ; 

call subroutine (path, dir_name, level, entryname, b_ptr, n__ptr) ; 

where: 

path 

is the pathname of the directory immediately superior to the directory that 
contains the current entry. (Input) 

dir_name 

is the name of the directory that contains the current entry. (Input) 

level 

is the number of levels deep from the base_path directory of the subtree. (Input) 
entryname 

is the primary name on the current entry. (Input) 
b_ptr 

is a pointer to the branch structure returned by hcs_$star_list for the current 
entry. (Input) 

n_ptr 

is a pointer to the names area for the immediately superior directory of the 
current entry returned by hcs_$star_list. (Input) 



Entry: sweep disk Sdir list 

This entry point operates in the same way as sweep_disk_ but is much less expensive 
to use and does not return date_time_contents_modified, date_time_used, or bit_count 

USAGE 

declare sweep_d i sk__$d i r__l i st entry (char(l68) aligned, entry); 

call sweep_d i sk_$d i r_1 i st (base_path, subroutine); 

The user-supplied subroutine is called in the same way as sweep_disk_, but b_ptr 
points instead to the branch structure returned by hcs_$star_dir_lisL See the 
hcs_$star_ subroutine. 
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NOTES 

If the base_path argument to the sweep_disk_ subroutine is the root (">") , the 
directory >process_dir_dir is omitted from the tree walk. 

The sweep_disk_ subroutine attempts to force access to the directories in the subtree 
by adding an ACL term of the form "sma Person.Project.tag" to each directory ACL, 
and deleting that ACL term when finished processing the directory. If the user does 
not have sufficient access to add this ACL term for a given directory, the subroutine 
processes those parts of the subtree under it where the user already has sufficient 
access to list the directories. 



Entry: sweep disk Sloud 

This entry point is used for debugging subsystems that use the sweep_disk_ subroutine. 
It sets an internal static flag in sweep_disk_ that causes sweep_disk_ to call com_err_ 
and report any errors encountered in listing directories or setting ACLs. Since 
sweep_disk_$loud takes no arguments, and should only be used for debugging, it can 
readily be invoked as a command ("sweep_disk_$loud") to cause sweep_disk_ to exhibit 
this debugging behavior for the rest of the process. There is no corresponding entry 
point to turn the switch off. Because this is a static switch, and affects all callers of 
sweep_disk_, it should not be turned on, except to debug, when it is important to 
understand the exact nature of any errors encountered. Normally, sweep_disk_ ignores 
errors and continues as best it can. 

USAGE 

declare sweep_d i sk_$ 1 oud entry () ; 
call sweep_d i sk_$ 1 oud () ; 



Name: system info 

The system_info_ subroutine allows the user to obtain information concerning system 
parameters. All entry points that accept more than one argument count their 
arguments and only return values for the number of arguments given. Certain 
arguments, such as the price arrays, must be dimensioned as shown. 
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Entry: system info Sabs chn 

This entry point returns the event channel and process ID for the process that is 
running the absentee user manager. 

USAGE 

declare system_i nf o_$abs_chn entry (fixed bin (71), bit (36) aligned); 

call system_i nf o_$abs_chn (ec, p_id) ; 

ARGUMENTS 

ec 

is the event channel over which signals to absentee_user_manager_ should be sent. 
(Output) 

P_id 

is the process ID of the absentee manager process (currently the initializer). 
(Output) 

Entry: system info Sabs prices 

This entry point returns the prices for CPU and real time for each absentee queue. 
USAGE 

declare system_i nf o_$abs_pr i ces entry ((h) float bin, (4) float bin); 

call system_i nf o_$abs_pr i ces (cpurate, real rate); 

ARGUMENTS 

cpurate 

is the price per CPU hour for absentee queues 1 to 4. (Output) 
realrate 

is the memory unit rate for absentee queues 1 to 4. (Output) 
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Entry: system info Saccess ceiling 

This entry point returns the system_hign access authorization or class. 
USAGE 

declare system_i nfo_$access_cei 1 i ng entry (bit (72) aligned); 

call system_i nf o_$access__cei 1 i ng (ceil); 

ARGUMENTS 

ceil 

is the access ceiling. (Output) 
Entry: system info Scategory names 

This entry point returns the 32-character long names and the eight-character short 
names for the access categories. 

USAGE 

declare system_i nf o_$category_names entry (dim(l8) char (32) , dim(l8) 
char (8)); 

call system_i nf o_$category_names (long, short); 

ARGUMENTS 

long 

is an array of the long level names. (Output) 
short 

is an array of the short level names. (Output) 
Entry: system inf o Sdef ault absentee queue 

This entry point returns the number of the default absentee queue used for submission 
of absentee jobs by the enter_abs_request, pll_abs, fortran_abs, etc., commands. 

USAGE 

declare system_i nf o_$def au 1 t_absentee_queue entry (fixed bin); 
call system_i nf o_$def aul t_absentee_queue (default_q); 
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ARGUMENTS 
default_q 

is the default absentee queue. (Output) 
Entry: system info $device prices 

This entry point returns the per-shift prices for system device usage. 
USAGE 

declare system_i nf o_$devi ce_pr i ces entry (fixed bin, ptr) ; 
call system_i nf o_$devi ce_pr i ces (ndev, dev_ptr) ; 
ARGUMENTS 
ndev 

is the number of devices with prices. (Output) 
dev__ptr 

points to an array where device prices are stored. (Input) 



In the above entry point, the user must provide the following array (in his storage) 
for device prices: 



STRUCTURE ELEMENTS 
dvt 

is the user structure. Only the first ndev of the 16 is filled in. 

device_id 

is the name of the device. 

device_price 

is the per-hour, per-shift price for the device. 



NOTES 



del 1 dvt (16) 



based (dev_ptr) aligned, 

char (8) , 

(0:7) float bin; 



2 device_id 
2 device_price 
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Entry: system^inf o = $installation_Jd 

This entry point returns the 32-character installation identifier that is typed in the 
header of the how_many_users command when the -long control argument is specified. 

USAGE 

declare system_i nfo_$ i nstal lat i on_id entry (char(*)); 
call system_i nfo_$i nstal lat ion_id (id); 
ARGUMENTS 
id 

is the installation identifier. (Output) 
Entry: system info $io__prices 

This entry point returns the prices for unit processing for each I/O daemon queue. 
USAGE 

declare system_i nf o_$ i o_pr i ces entry ((h) float bin); 

call system_i nf o_$ i o_pr i ces (rp) ; 

ARGUMENTS 

rp 

is the price per 1000 lines for each I/O daemon queue. (Output) 

This entry point returns the clock time of the last shutdown or crash and an 
eight-character string giving the ERF (error report form) number of the last crash 
(blank if the last shutdown was not a crash). 

USAGE 

declare system_i nf o_$ 1 ast_shutdown entry (fixed bin (71)1 char (*) ) ; 

call system_i nf o_$ 1 ast_shutdown (time, erf no) ; 

ARGUMENTS 

time 

is the clock time of the last shutdown. (Output) 
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erf no 

is the ERF number of the last crash, or blank. (Output) 
Entry: system info Sieve! names 

This entry point returns the 32-character long names and eight-character short names 
for sensitivity levels. 

USAGE 

declare system_i nf o_$ 1 evel_names entry (dim (0:7) char (32) , dim (0:7) 
char (8)); 

call system_info_$level_names (long, short); 

ARGUMENTS 

long 

is an array of the long level names. (Output) 
short 

is an array of the short level names. (Output) 

Entry: system info $max rs number 

This entry point returns the largest valid rate structure number. 
USAGE 

declare system_i nf o_$max_rs_number entry (fixed b i n (1 7) ) » 
call system_i nf o_$max_rs_number (rs_number) ; 
ARGUMENTS 
rs_number 

is the largest valid rate structure number. If it is zero, there are no rate 
structures defined, other than the default one in installation_parms. (Output) 
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Entry: system inf o $next shif t change 

This entry point returns the number of the current shift, the time it started, the time 
it will end, and the number of the next shift. 

USAGE 

declare system_i nf o_$next_sh i f t__change entry (fixed bin, fixed bin(71), 
fixed bin, fixed bin (71); 

call system_i nf o_$next_sh i f t_change (now__shift, change_time, new_shift, 
start_time) ; 

ARGUMENTS 

now_shift 

is the current shift number. (Output) 
change_time 

is lug Liuifc mv aim i wuaiigira. vwuipui; 

new_shift 

is the shift after change_time. (Output) 
start_time 

is the time the current shift started. (Output) 



Entry: system info Snext shutdown 

This entry point returns the time of the next scheduled shutdown, the reason for the 
shutdown, and the time when the system will return, if these data are available. 

USAGE 

declare system_i nf o_$next_shutdown entry (fixed bin (71), char (*) , 
fixed bin (71) ) ; 

call system_i nf o_$next_shutdown (td, rsn, tn) ; 

ARGUMENTS 

td 

is the time of the next scheduled shutdown. If none is scheduled, this is 0. 
(Output) 

rsn 

is the reason for the next shutdown (a maximum of 32 characters). If it is not 
known, it is blank. (Output) 
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tn 

is the time the system will return. If it is not known, it is 0. (Output) 
Entry: system info_$prices 

This entry point returns the per-shift prices for interactive use. 
USAGE 

declare system_i nf o_$pr i ces entry ((0:7) float bin, (0:7) float bin, 
(0:7) float bin, (0:7) float bin, float bin, float bin); 

call system_i nf o_$pr i ces (cpu, log, pre, cor, dsk, reg) ; 

ARGUMENTS 

cpu 

is the CPU-hour rate per shift. (Output) 

log 

is the connect-hour rate per shift (Output) 

pre 

is the process-hour rate per shift (Output) 

cor 

is the page-second rate for main memory per shift. (Output) 

dsk 

is the page-second rate for secondary storage. (Output) 

reg 

is the registration fee per user per month. (Output) 

Entry: system info Sresource price 

This entry point returns the price of a specified resource. 
USAGE 

declare system_i nf o_$resource_pr i ce entry (char (*) , float bin, fixed bin 
(35) ) ; 

call system_i nf o_$resource_pr i ce entry (name, price, code); 
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ARGUMENTS 
name 

is the name of the resource. (Input) 
price 

is the price of the resource in dollars per unit. (Output) 

code 

is a standard status code. It will be error_table_$noentry if the resource is not in 
the price list. (Output) 



Entry: system info $rs name 

This entry point returns the rate structure name corresponding to a rate structure 
number. 

USAGE 

declare system_i nf o_$rs_name entry (fixed bin(17)» char (*) , 
fixed bin (35)) ; 

call system_i nf o_$rs_name (rs_number, rs_name, code); 

ARGUMENTS 

rs_number 

is the number of a rate structure. (Input) 
rs_name 

is the name corresponding to rs_number. (The name can be up to 32 characters 
long.) (Output) 

code 

is zero if no error occurred, or error_table_$noentry if rs_number is not the 
number of a defined rate structure. (Output) 



Entry: system info $rs number 

This entry point returns the rate structure number corresponding to a rate structure 
name. 

USAGE 

declare system_i nf o_$rs_number entry (char (*) , fixed bi n (17) i 
fixed bin (35)) ; 

call system_i nf o_$rs_number (rs_name, rs_number, code); 
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ARGUMENTS 
rs_name 

is the name of a rate structure. {Input) 
rs_number 

is the number corresponding to rs_name. (Output) 

code 

is zero if no error occurred, or error_table_$noentry if rs_name is not the name 
of a rate structure. (Output) 

Entry: system__info_$shift__table 

This entry point returns the local shift definition table of the system. 
USAGE 

declare system_J nf o__$sh i f t_table entry ((336) fixed bin); 

call system_info_$shif t_table (stt) ; 

ARGUMENTS 

stt 

is a table of shifts, indexed by half -hour within the week e.g., stt(l) gives the 
shift for 0000-0030 Mondays. (Output) 

Entry: system info__$sysid 

This entry point returns the eight-character system identifier that is typed in the 
header of the who command and at dial-up time. 

USAGE 

declare system_i nf o_$sys i d entry (char(*)); 
call system_i nf o_$sysid (sys); 
ARGUMENTS 
sys 

is the system identifier that identifies the current system. (Output) Normally this 
is the Multics Release number (eg, MR10.1). 
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Entry: system info_$timeup 

This entry point returns the time at which the system was last started up. 
USAGE 

declare system_i nf o_$t imeup entry (fixed bin (71)); 

call system_i nfo_$t imeup (tu) ; 

ARGUMENTS 

tu 

is when the system came up. (Output) 
Entry: system info_$titles 

This entry point returns several character strings that more formally identify the 
installation. 

USAGE 

declare system_i nf o_$t i 1 1 es entry (char (*) , char (*) , char (*) , char(*)); 

call system_i nf o_$t i 1 1 es (c, d, cc, dd) ; 

ARGUMENTS 

c 

is the company or institution name (a maximum of 64 characters). (Output) 

d 

is the department or division name (a maximum of 64 characters). (Output) 

W 

is the company name, double spaced (a maximum of 120 characters). (Output) 

dd 

is the department name, double spaced (a maximum of 120 characters). (Output) 
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Entry: system__info__$trusted — path 

This entry point returns bit flags indicating which trusted path facilities are required 
by the site. At present, only one, "iogin" is implemented under the control of the 
"trusted_path_login" installation parameter, to disable the use of logout -hold and 
new_proc -authorization, 

USAGE 

declare system_i nf o_$trusted_path entry () returns (bit (36) aligned; 

string (trusted_path) * system_i nf o_$trusted_path () ; 

declare 1 trusted_path_f lags aligned 

2 login bit(l) unaligned, 
2 pad bit (35) unaligned; 

ARGUMENTS 

trusted_path_login 

indicates the state of the "trusted_path_login" installation parameter. 



Entry: system info Susers 

This entry point returns the current and maximum number of load units and users. 
USAGE 

declare system_i nf o_$users entry (fixed bin, fixed bin, fixed bin, 
f i xed bin); 

call system_i nf o_$users (mn, nn, mu, nu) ; 

ARGUMENTS 

mn 

is the maximum number of users. (Output) 

nn 

is the current number of users. (Output) 

mu 

is the maximum number of load units (times 10). (Output) 

nu 

is the current number of load units (times 10). (Output) 
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Entry: system info $version_id 

This entry point returns the eight-character version identifier that is written on the 
hardcore system tape currently running. This might be set to "37-19.3", which is an 
internal version number. This information is different from the information that is 
obtained with the system_info_$sysid entry point. 

USAGE 

declare system_j nf o$_vers ion_i d entry (char(*)); 
call system_i nf o_$vers i on_i d (vers); 
ARGUMENTS 
vers 

is the version identifier that identifies the current version of the system. (Output) 



Name; tcCO get m&CTO 

The teco _get_macro_ subroutine is called by teco to search for an external macro. 
By default the following directories are searched: 

1. working directory 

2. home directory 

3. >system_library_tools 

USAGE 

declare teco_get_macro_ entry (char (*) aligned, ptr, fixed bin, 
fixed bin(35)) ; 

call teco_get_macro_ (mname, mptr, mien, code); 

ARGUMENTS 

name 

is the name of the macro to be found. (Input) 

mptr 

is a pointer to the macro. (Output) 

mien 

is the length of the macro. (Output) 
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code 

is a standard Multics status code. (Output) 



Name: term 

The term_ subroutine terminates the reference names of a segment or multisegment 
file (MSF) and removes the segment from the caller's address space and the 
appropriate combined linkage segment It also unsnaps any links in the combined 
linkage segments that contain references to the file 

USAGE 

declare term_ entry (char (*) , char (*) , fixed bin (35)); 

call term_ (dir_path, entryname, code); 

ARGUMENTS 

dir_path 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment or MSF. (Input) 

code 

is a standard status code. (Output) 



Entry: term Srefname 

This entry point performs the same function as the term_ entry point given a 
reference name rather than a pathname. 

USAGE 

declare term__$ref name entry (char (*) , fixed bin(35))» 

call term_$ref name (ref_name, code); 

ARGUMENTS 

ref_name 

is the reference name of the segment or MSF. (Input) 

code 

is a standard status code. (Output) 
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Entry: term_$seg ptr 

This entry point performs the same function as the term_ entry point given a pointer 
to the segment If the segment pointed to is a component of an object MSF, all the 
components are terminated. 

USAGE 

declare term__$seg_ptr entry (ptr, fixed bin(35))» 
call term_$seg__ptr (seg_ptr , code); 
ARGUMENTS 
seg_ptr 

is a pointer to the segment. (Input) 

code 

is a standard status code. (Output) 



Entry: term Ssingie rsfnssis 

| This entry point allows termination of a single reference name. The segment or MSF 
is not made unknown unless the specified reference name was the only reference name 
| initiated for the file. 

USAGE 

declare term_$s i ng 1 e_ref name entry (char (*) , fixed bin (35)); 

call term_$s i ngl e_ref name (ref_name, code); 

ARGUMENTS 

ref_name 

| is a reference name of the file. (Input) 
code 

is a standard status code. (Output) 
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Entry: term__ Sunsnap 

This entry point unsnaps links to the segment or MSF but does not terminate any 
reference names or make the unknown. 

USAGE 

declare term_$unsnap entry (ptr, fixed bin(35))» 
call term_$unsnap (seg_ptr, code); 
ARGUMENTS 
seg_ptr 

is a pointer to the file. (Input) 

code 

is a standard status code. (Output) 
NOTES 

The term_ subroutine performs the same operation as certain hcs_ entry points; 
however, the term_ entry points also unsnap links and deal with object MSFs 
correctly. The term_ entry points and corresponding hcs_ entry points are: 

term_ hcs_$terminate_file 
term_$seg_ptr hcs_$terminate_seg 
term_$single_ref name hcs_$terminate_name 

Use of the term_ subroutine is preferred to the corresponding hcs_ entry points since 
the term_ subroutine unsnaps links in addition to terminating the segment The term„ 
subroutine also deals with terminating portions of object MSFs by terminating all the 
components to prevent them from becoming inconsistent. 
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Name: terminate file 



This subroutine performs common operations that are often necessary after a program 

has finished using a segment It optionally sets the bit count, truncates the segment, 
ensures that bits in the last word of the segment after the bit count are zero, and 

terminates a null reference name from the segment It may also ensure that all 

modified pages of the segment are no longer in main memory. It can also be 
instructed to delete the segment 

USAGE 



declare terminate file_ entry (pointer, fixed bin(24), bit(*), 
fixed bin (35)) ; 



call termi nate_f Me_ (seg_ptr, bit_count, switches, code); 



ARGUMENTS 



seg_ptr 

is a pointer to the segment (Input/Output) If null on input, no action is taken. 
It is set to null after the segment is terminated. 



bit_count 

is the new bit count of the segment (Input) 



switches 

control the action of this subroutine. (Input) See the "Notes" section below. 



code 

is a standard status code. (Output) 



NOTES 



The bits in the switches bit string mean the following: 

del I term i nate_f i 1 e__sw i tches based, 

2 truncate bit (1) unaligned, 

2 set_bc bit (1) unaligned, 

2 terminate bit (1) unaligned, 

2 force_write bit (1) unaligned; 

2 delete bit (1) unaligned; 



STRUCTURE ELEMENTS 



truncate 
(Input) 

"l"b truncate the segment to the word containing the bit count and ensure that 

the bits following the bit count in the last word of the segment are zero. 
"0"b don't truncate the segment. 
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set_bc 
(Input) 

'T'b set the bit count of the segment to bit_count 
"0"b don't set the bit count 

terminate 
(Input) 

"l"b terminate a null reference name on the segment 
"0"b don't terminate the segment 

force_write 
(Input) 

"l"b ensure that modified pages of the segment are no longer in main 
memory. 

"0"b allow modified pages to remain in main memory. 

delete 

(Input) 

"l"b instructs the program to delete the program. 
"0"b don't delete the segment 

If a request is made to delete the segment any other options selected 
are performed first in case it is not possible to delete the segment. 

NOTES 

The terminate_file_switches structure is declared in terminate_file. incl.pl!. The named 
constants in the "List of named constants" section are also declared with one or more 
of the above bits on. 

LIST OF NAMED CONSTANTS 



TERM_FILE_TRUNC 

truncate the segment to bit__count bits 

TERM_FILE_BC 

set the bit count to bit_count 

TERM_FILE_TERM 

terminate a null reference name on the segment 

TERM_FILEJTRUNC„BC 

truncate the segment to the bit_count bits and set the bit count to bit_count 

TERM_FILE_TRUNC_BC_TERM 

truncate the segment to the bit_count bits, set the bit count to bit_count and 
terminate a null reference name on the segment 



11/86 



2-857 



AG93-05A 



terminate_file_ 



terminate_process_ 



| TERM_FILE_FORCE_WRITE 

ensure that modified pages of the segment are no longer in main memory 

| TERM_FILE_DELETE 
delete the segment 

This subroutine should never be called from a cleanup handler with the truncate or 
set_bc switches on. In a cleanup handler, seg_ptr may contain an invalid segment 
number. 

The force_write switch should only be used when data integrity is absolutely essential. 
The use of the force_write switch may introduce a substantial real time delay in 
execution, since this subroutine does not return until all modified pages are no longer 
in main memory. However, use of this switch protects data against unrecoverable main 
memory failures. 

EXAMPLES 

The following calls illustrate the two ways to set the switches to set the bit count and 
terminate a segment Using the named constants: 

I call terminate fiie_ (seg pointer, bit count, 

1 TERM_FILE~BC | TERM_Fl LE_TERM, code); 

Using a structure: 

I del 1 tfs aligned like termi nate__f i 1 e_swi tches 

string (tfs) - ""b; 
tfs.set_bc - "T'b; 
tfs. terminate = "T'b; 

call termi nate_f i le__ (p, be, string (tfs), code); 



Namci terminate prGCcSS 

This procedure causes the process in which it is called to be terminated. The 
arguments determine the exact nature of the termination. 

USAGE 

declare termi nate_process_ entry (char (*) , ptr) ; 
call termi nate_process_ (action, info_ptr); 



11/86 



2-858 



AG93-05A 



terminate_process_ terminate_process_ 



ARGUMENTS 
action 

specifies one of four general actions to be taken upon process termination. 
(Input) The permissible values are logout, new_proc, fatal_error, or init_error (see 
"Notes"). 

info_ptr 

points to more specific information about the action to be taken at termination. 
(Input) The structure pointed to by info_ptr depends upon action (see "Notes"). 

NOTES 

If action is logout then the user's process is logged out The info_ptr points to: 

del 1 logout_info aligned, 

2 version fixed bin, 

2 hold bit(l) unaligned, 

2 brief bit(l) unaligned, 

2 pad bit (3*0 unaligned, 

STRUCTURE ELEMENTS 

version 

must be 0. 

hold 

must be "l"b if the terminal associated with this process is not to be hung up, so 
that another user may log in. 

brief 

must be "l"b if the logout message is to be suppressed. 

pad 

must be "0"b. 

If action is new_proc, then the user's current process is logged out and a new process 
is created. The info_ptr points to: 

del 1 new_proc_i nf o aligned, 

2 version fixed bin, 

2 author ization_opt son bit(l) unaligned, 

2 pad bit (35) unaligned, 

2 new_author izat ion bit (72) aligned; 
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STRUCTURE ELEMENTS 

version 

must be 1. 

authorization_option 

must be 1 if new_authorization is to be used. 

pad 

must be 0. 

new_authorization 

is the authorization of the new process. 

If action is fatal_error, then the user's current process is terminated due to an 
unrecoverable error. A fatal error message is printed on the terminal and a new 
process is created. The info_ptr points to: 

del 1 f ata l_error_i nf o aligned, 

2 version fixed bin. 

2 status_code fixed bin (35); 

STRUCTURE ELEMENTS 

version 

must be 0. 

status_code 

is a standard system status code (in error_table_) indicating the nature of the 
fatal error, the corresponding error message will be printed on the user's console. 

If action is init_error, then the user's process is logged out and a message indicating 
that his process could not be initialized is printed. The info_ptr points to: 

del 1 i ni t_error_i nf o aligned, 

2 version fixed bin, 

2 status_code fixed bin (35); 

STRUCTURE ELEMENTS 

version 

must be 0. 

status_code 

is a standard Multics code indicating the nature of the error. 
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Name: timed io Sget chars 

This entry point reads 9-bit bytes from the unstructured file or device to which an 
I/O switch is attached. The switch must be open for stream_input or stream_input_output. 
This entry point has the same function as the iox_$get_chars entry point except that it 
returns error_table_$timeout if it cannot complete its operation within the time 
specified. 

USAGE 

declare t imed_io_$get_chars entry (ptr, fixed bi n (7 1) * ptr, fixed 
bin (21), fixed bin (21), fixed bin (35)); 

call t imed_i o_$get_chars (iocb_ptr, timeout, buff_ptr, buff_len, 
chars_read, code) ; 

ARGUMENTS 

iocb_ptr 

points to the switch's control block. (Input) 
timeout 

is the number of microseconds to wait before returning the code error_table_$ timeout. 
buff_ptr 

points to the byte-aligned buffer into which bytes are to be read. (Input) 
buff_len 

is the number of bytes to be read where buff Jen >= 0. (Input) 
chars_read 

is the number of bytes actually read. (Output) 

code 

is an I/O system status code. (Output) 
NOTES 

See also the get_chars_timeout control order of the tty_ I/O module. 
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Entry: timed io Sgel chars$get line 

This entry point reads 9-bit bytes from the unstructured file or device to which an 
I/O switch is attached. The switch must be open for stream_input or stream_input_output. 
Bytes are read until the input buffer is filled, a newline character is read, or end of 
file is reached, whichever occurs first This entry point has the same function as the 
iox_$get_line entry point except that it returns error_table_$timeout if it cannot 
complete its operation within the time specified. 

USAGE 

declare t imed_io_$get_l i ne entry (ptr, fixed bin (70, ptr, fixed 
bin(21), fixed bin(21), fixed bin(35)); 

call timed_io_$get_l i ne (iocb_ptr, timeout, buff_ptr, buff_len, 
chars_read, code) ; 

ARGUMENTS 

iocb_ptr 

points to the switch's control block. (Input) 
timeout 

is the number of microseconds to wait before returning the code error_table_$timeout. 
buff_ptr 

points to the byte-aligned buffer into which bytes are to be read. (Input) 
buff Jen 

is the number of bytes to be read where buff Jen >= 0. (Input) 
chars_read 

is the number of bytes actually read. (Output) 

code 

is an I/O system status code. (Output) 
NOTES 

See also the get_line_timeout control order of the tty_ I/O module. 
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Entry: timed io $get chars$put chars 

This entry point writes a specified number of 9-bit bytes to the unstructured file or 
device to which an I/O switch is attached. The switch must be open for 
stream_output or stream_input_outpuL Tnis entry point has the same function as the 
iox_$put_chars entry point except that it returns error_table_$timeout if it cannot 
complete its operation within the time specified. 

USAGE 

declare timed_io_$put_chars entry (ptr, fixed bin (71), ptr, fixed 
bin(21), fixed bin(21), fixed bin (35)); 

call t imed_i o_$put_chars (iocb_ptr, timeout, buff_ptr, buff_Jen, 
chars_wr i tten, code); 

ARGUMENTS 

iocb_ptr 

points to the switch's control block. (Input) 
timeout 

is the number of microseconds to wait before returning the code error_table_$ timeout 
buff_ptr 

points to the byte-aligned buffer into which bytes are to be read. (Input) 
buff_len 

is the number of bytes to be read where buff_len >= 0. (Input) 

chars_written 

is the number of bytes actually written. (Output) 

code 

is an I/O system status code. (Output) 
NOTES 

See also the put_chars_timeout control order of the tty_ I/O module. 
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Name: timer manager 

The timer_manager_ subroutine allows many CPU usage timers and real-time timers to 
be used simultaneously by a process. The caller can specify for each timer whether a 
wakeup is to be issued or a specified procedure is to be called when the timer goes 
off. If a procedure is to be called, the calling procedure can specify a data pointer 
to pass to that procedure. 

The timer_manager_ subroutine fulfills a specialized need of certain sophisticated 
programs. A user should be familiar with interprocess communication in Multics and 
the pitfalls of writing programs that can run asynchronously within a process. For 
example, if a program does run asynchronously within a process and it does input or 
output with the tty_ I/O module, then the program should issue the "start" control 
order of tty_ before it returns. This is necessary because a wakeup from tty_ may be 
intercepted by the asynchronous program. Most pitfalls can be avoided by using only 
the timer_manager_$sleep entry point. 

For most uses of the timer_manager_ subroutine, a cleanup condition handler, which 
resets all the timers that might be set by a software subsystem, should be set up. If 
the subsystem is aborted and released, any timers set up by the subsystem can be reset 
instead of going off at undesired times. 

To be used, the timer_manager_ subroutine must be established as the condition 
handler for the alrm and cput conditions. This is done automatically by the standard 
Multics environment. 



GENERIC ARGUMENTS 

At least one of the following arguments is called in all of the timer_manager_ entry 

points. For convenience, these common arguments are described below rather than in 
each entry paint description. 

channel 

is the name of the event channel (fixed binary(71)) over which a wakeup is 
desired. Two or more timers can be running simultaneously, all of which may, if 
desired, issue a wakeup on the same event channel. 

routine 

is a procedure entry point that is called when the timer goes off. The entry 
value must be valid when the routine is invoked, i.e., if the routine is an internal 
procedure, the procedure that created the entry value must still be on the stack. 
The routine is called as follows: 

declare routine entry (ptr, char (*) , ptr, ptr) ; 
call routine (mc_ptr, name, wc_ptr, data_ptr) ; 
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ARGUMENTS 
mc_ptr 

is a pointer to a structure containing the machine conditions at the time of the 
process interrupt (Input) 

name 

is the condition name: alrm for a real-time timer and cput for a CPU timer. 
(Input) 

wc_ptr 

is a pointer to crawlout machine conditions. (Input) This pointer will invariably 
be null, and is only provided for compatibility with other condition handlers. 

data_ptr 

is a copy of the pointer passed to the timer_manager_ entry point which 
established the timer. (Input) 

(See the signal, subroutine for a full description of the mc_ptr and name 
arguments.) Two or more timers can be running simultaneously, all of which may, 
if desired, call the same routine. 

time 

is the time (fixed binary(71)) at which the wakeup or call is desired. 

flags 

is a 2-bit string (bit(2)) that determines how time is to be interpreted. The 
high-order bit indicates whether it is an absolute or a relative time. The 
low-order bit indicates whether it is in units of seconds or microseconds. 
Absolute real time is time since January 1, 1901, 0000 hours Greenwich mean 
time, i.e., the time returned by the clock_ subroutine. Absolute CPU time is total 
virtual time used by the the process, i.e., the time returned by the 
cpu_time_and_paging_ subroutine. Relative time begins when the timer_manager_ 
subroutine is called. 

"ll"b means relative seconds 

"10"b means relative microseconds 

"01"b means absolute seconds 

*'00"b means absolute microseconds 

data_ptr 

is a pointer to a data structure which is to be associated with this particular 
timer. This is useful for those applications which use timers to manage various 
related processes, using the same program to manipulate different data. Since 
earlier versions of timer_manager_ did not provide this service, data_ptr is an 
optional argument to all entry points which use it 
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Entry: timer manager $alarm__call 

This entry point sets up a real-time timer that calls the routine specified when the 
timer goes off. 

USAGE 

del timer_manager_$alarm_cal 1 entry (fixed bin (71) • bit (2), entry, ptr) ; 
call t imer_manager_$a1 arm_cal 1 (time, flags, routine, data_ptr) ; 



Entry: timer manager Salarm call inhibit 

This entry point sets up a real-time timer that calls the handler routine specified 
when the timer goes off. The call is made with all interrupts inhibited (i.e., all 
interprocess signal (IPS) are masked off). When the handler routine returns, interrupts 
are reenabled. If the handler routine does not return, interrupts are not reenabled and 
the user process may malfunction. 

USAGE 

del t imer_manager_$al arm_cal l_i nhibi t entry (fixed bin (71), bit (2), 
entry, ptr) ; 

call t imer_manager_$al arm_cal l_i nh i bi t (time, flags, routine, data_ptr) ; 



Entry: timer manager Salarm wakeup 

This entry point sets up a real-time timer that issues a wakeup on the event channel 

specified when the timer goes off. The event message passed is the string "alarm ' 

(three underscores). (See the ipc_ subroutine for a discussion of event channels.) 

USAGE 

declare t imer_manager_$alarm_wakeup entry (fixed bin (71), bit (2), 
fixed bin(7D) ; 

call timer_manager_$alarin_wakeup (time, flags, channel); 
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Entry: timer manager Scpu call 

This entry point sets up a CPU timer that calls the routine specified when the timer 
goes off. 

USAGE 

del t imer_manager_$cpu_cal 1 entry (fixed bin (71), bit (2), entry, ptr) ; 
call t imer_manager_$cpu_cal 1 (time, flags, routine, data_ptr) ; 



Entry: timer manager $cpu call inhibit 

This entry point sets up a CPU timer that calls the handler routine specified when the 
timer goes off. The call is made with all interrupts inhibited (i.e., all IPS are masked 
off). When the handler routine returns, interrupts are reenabled. If the handler 
routine does not return, interrupts are not reenabled and the user process may 
malfunction. 

USAGE 

del t imer_manager_$cpu_cal l_inhibi t entry (fixed b i n (7 1 ) > bit (2), entry, 
ptr) ; 

call t imer_manager_$cpu_cal l_i nhibi t (time, flags, routine, data_ptr) ; 



Entry: timer manager $cpu wakeup 

This entry point sets up a CPU timer that issues a wakeup on the event channel 
specified when the timer goes off. The event message passed is the string "cpu_time". 

USAGE 

declare t imer_manager_$cpu_wakeup entry (fixed bin (71), bit (2), 
fixed bin(7D) ; 

call t imer_manager_$cpu_wakeup (time, flags, channel); 
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Entry: timer manager $reset alarm call 

This entry point turns off all real-time timers that call the routine specified when 
they go off. 

USAGE 

del timer_manager_$reset_alarm_cal 1 entry (entry); 
call timer_manager_$reset_alarm_cal 1 (routine); 
or: 

del timer_manager_$reset_alarm_cal 1 entry (entry, ptr) ; 
call t imer_manager_$reset_al arm_cal 1 (routine, data_ptr) ; 
NOTES 

If the data_ptr is provided, all real-time timers which are to call the given routine 
with that value of data_ptr are cancelled. Otherwise, all real-time timers which are to 
call that routine with any value of data_ptr are cancelled. 

Entry: timer manager Sreset alarm wakeup 

This entry point turns off all real-time timers that issue a wakeup on the event 
channel specified when they go off. 

USAGE 

declare t imer_manager_$reset_al arm_wakeup entry (fixed bin (71)); 
call t imer_manager$reset_al arm_wakeup (channel); 

Entry: timer manager Sreset cpu call 

This entry point turns off all CPU timers that call the routine specified when they go 
off. 
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USAGE 

declare t imer_manager_$reset_cpu_cal 1 entry (entry); 
call t imer_manager_$reset_cpu_cal 1 (routine); 
or : 

declare t imer_manager_$reset_cpu_cal 1 entry (entry, ptr) ; 
call timer_manager_$reset_cpu_cal 1 (routine, data_ptr) ; 
NOTES 

If the data_ptr is provided, all CPU timers which are to call the given routine with 
that value of data_ptr are cancelled. Otherwise, all CPU timers which are to call the 
routine with any value of data_ptr are cancelled. 

Entry: timer manager Sreset cpu wakeup 

This entry point turns off all CPU timers that issue a wakeup on the event channel 
specified when they go off. 

USAGE 

declare t imer_manager_$reset_cpu_wakeup entry (fixed bi n (71) ) ; 
call t imer_manager_$reset_cpu_wakeup (channel); 

Entry: timer manager $sleep 

This entry point causes the process to go blocked for a period of real time. Other 
timers that are active continue to be processed whenever they go off; however, this 
routine does not return until the real time has been passed. 

USAGE 

del timer_manager_$ sleep entry (fixed bi n (71) • bit(2)); 
call t imer_manager_$ sleep (time, flags); 

The time is always real time; however, it can be relative or absolute, seconds or 
microseconds, as explained above in "Generic Arguments." 



2-869 



AG93-05 



transaction_manager_ 



transaction_manager_ 



Name: transaction manager 

Entry points in transaction_manager_ begin and end transactions on behalf of users, 
return information about transactions, and recover transactions after system failure. 

See the section entitled "Multics Data Management" in the Multics Programmer's 
Reference Manual, Order No. AG91, for a complete description of transactions and 
their use. 



Entry: transaction manager (abandon txn 

This entry point relinquishes control of the current transaction, causing it to be 
adjusted (aborted unless a commit was already in progress) by the DM daemon 
(Data_ManagementDaemon). The caller is immediately given a new TDT entry and 
can begin another transaction. 

USAGE 

declare transact i on_mariager_$abandGn_txn entry (bit (3°) aligned, fixed 
bin (35)); 

call transact i on_manager_$abandon_txn (txn_id, code); 

ARGUMENTS 

txn_id 

is the identifier of the current transaction, or "0"b to default to the current 
transaction. (Input) If txn_id is neither "0"b nor the transaction identifier of the 
current transaction, dm_error_$transaction_not_current is returned. This argument 
can be used as a check to be sure which transaction is being abandoned. 

code 

ID a ouuiuaiu ojr lAsin jiaiiu kuuv. wuij/ui; Ji t wuu aw l/w. 

dm_error_$no_current_transaction 

No current transaction is defined for this process. 

dm_error_$not_own_transaction 

A process can only abandon its own transaction. 

dm_error_$transaction_suspended 

The current transaction is suspended and therefore cannot be abandoned. 
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Entry: transaction manager $abort txn 

This entry point aborts the current transaction, returning all modified DM files to the 
state they were in before the transaction began. 

USAGE 

declare transact i on_manager_$abort_txn entry (bit (36) aligned, fixed 
bin (35))? 

call transact i on_manager_$abort_txn (txn__id, code); 

ARGUMENTS 

txn_id 

is the identifier of the current transaction, or "0"b to default to the current 
transaction. (Input) If txn_id is neither "0"b nor the transaction identifier of the 
current transaction, dm_error_$transaction_not_current is returned. This argument 
can be used as a check to be sure which transaction is being aborted. 

code 

is a standard system status code. (Output) It can also be: 

dm_error_$no_current_transaction 

No current transaction is defined for this process. 

dm_error_$not_own_transaction 

A process can only abort its own transaction. 

dm_error_$ transaction_suspended 

The current transaction is suspended and therefore cannot be aborted. 

dm_error_$unf inished_commit 

The transaction was left in the middle of a commit operation. It is possible 
to call $commit_txn to complete the commit, or call either $abandon_txn or 
$kill_txn. 

NOTES 

If the transaction has already been abandoned, this entry point causes the DM daemon 
to abort it immediately. 

This entry point will retry abort of a transaction that was left in an error state by a 
previous abort or rollback. It will not attempt abort of a transaction left in error by 
any other operation. 
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Entry: transaction manager $begin txn 

This entry point begins a transaction on behalf of the caller, by generating a unique 
transaction identifier and recording it in a TDT entry as the current transaction for 
the process. Other information, such as owner name, begin time, and transaction state 
(in-progress) are also recorded. The transaction id is passed to the before journal 
manager to begin the transaction. 

USAGE 

declare transact ion_manager_$begin_txn (fixed bi n (1 7) » bit(36), bit(36) 
aligned, fixed bin (35)); 

call transact i on_manager_$beg i n_txn (beg i njnode, 
bef ore_journa l_open i ng_i d, txn_id, code) ; 

ARGUMENTS 

begin_mode 

determines which of several protocols to use. (Input) The only mode currently 
available is normal mode. 

TM_NORMAL_MODE 

requires locks to accompany all gets and puts, and requires all updates to be 
journalized. 

bef ore_journal_opening_id 

is the opening identifier of the before journal to be used by this transaction. 
(Input) If zero, a before journal is assigned by default to this transaction. 

txn_id 

is the identifier of the newly created transaction. (Output) It is generated by 
transaction_manager_$begin_txn and is guaranteed to be unique across all Multics 
systems. Transaction identifiers are not reusable. 

code 

is a standard system status code. (Output) It can also be: 

dm_error_$invalid_mode 

The specified begin_mode is not currently supported. 

dm_error_$no_begins 

Transactions are not allowed to be begun because DM daemon has disallowed 

beginning new transactions, for example when preparing to do a system wide 
DMS shutdown. 

dm_error_$transaction_suspended 

A transaction cannot be begun because a suspended one already exists. 
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dm_error_$transaction_in_progress 

A transaction cannot be begun because one is already active. 



Entry: transaction manager Scommit txn 

This entry point commits the current transaction. Any modifications made to DM files 
since the transaction began become permanent and visible to other transactions, as if 
all the changes were made in the same instant. 

USAGE 

declare transact i on_manager_$commi t_txn entry (bit (36) aligned, fixed 
bin (35)); 

call transact i on_manager_$commi t_txn (txn_id, code); 

ARGUMENTS 

txn_id 

is the identifier of the current transaction, or "0"b to default to the current 
transaction. (Input) If txn_id is neither "0"b nor the transaction identifier of the 
current transaction, dm_error_$transaction_not_current is returned. This argument 
can be used as a check to be sure which transaction is being committed. 

code 

is a standard system status code. (Output) It can also be: 

dm_error_$no_current_transaction 

No current transaction is defined for this process. 

dm_error_$not_own_transaction 

A process can only commit its own transaction. 

dm_error_$transaction_suspended 

The current transaction is suspended and therefore cannot be committed. 

dm_error_$unf inished_abort 

The transaction was left in the middle of an abort operation. It is possible 
to call $abort_txn to complete the abort, or call either $abandon_txn or 
$kill_txn. 

dm_error_$unf inished_rollback 

The transaction was left in the middle of a rollback operation. It is possible 
to call $rollback_txn to complete the rollback, call $abort_txn to abort the 
transaction, or call either $abandon_txn or $kill_txn. 
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NOTES 

This entry point will retry commit of a transaction that was left in an error state by 
a previous commit. It will not, however, attempt to commit a transaction left in error 
by any other operation. 



Entry: transaction manager $get current ids 

This entry point returns the identifier of the current transaction, the most recent 
checkpoint number, and the number of times this transaction has been rolled back. 

USAGE 

declare transact i on_manager_$get_current_i ds entry (bi t (36) aligned, 
fixed bin, fixed bin, fixed bin (35)); 

call transaction_manager_$get_current_ids (txn_id, checkpoi nt_i d, 
rol lback_count, code) ; 

ARGUMENTS 

txn_id 

is the identifier of the current transaction. (Output) 
checkpoint_id 

is the number of the most recent checkpoint This value is currently always zero. 
(Output) 

rollback_count 

is the number of times this transaction has been rolled back. (Output) 

code 

is a standard system status code. (Output) It can also be: 

dm_error_$no_current_transaction 

there is no transaction for the user process. 

dm_error_$transaction_suspended 

the current transaction is suspended. The returned information is still valid. 
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Entry: transaction manager $get current txn id 

This entry point returns the identifier of the current transaction, and tells whether the 
transaction is suspended or in error. See "Notes" below for a table of transaction 
identifiers and error codes returned. 

USAGE 

declare transact ion_manager_$get_current_txn_id entry (bit (36) aligned, 
f i xed bin (35) ) ; 

call transact i on_manager_$get_current_txn_id (txn_id, code); 

ARGUMENTS 

txn_id 

is the identifier of the current transaction. (Output) 

code 

is one of the codes listed below. (Output) 
NOTES 

The txn_id and code values returned depend on the status of the current transaction: 

txn id code 



1. Txn in progress. valid id 0 

2. No current txn. 0 dm_error_$no_current_transact i on 

3. Txn suspended. valid id dm_error_$ transact i on_suspended 
k. Txn in error. valid id dm_error_$unf i ni shed_abort 

or: dm_er ror_$unf i ni shed_commi t 

or: dm error $unfinished rollback 



Entry: transaction manager $get state description 

This entry point generates a character string description of a numeric state returned by 
transaction_manager_$get_txn_inf 0 or transaction_manager_$get_txn_inf o_index. 

USAGE 

declare transact i on_manager_$get_state_descr i pt i on entry (fixed bin) 
returns (char (*) ) ; 

state_descr ipt ion = transact i on_manager_$get_state_descr ipt ion (state); 
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Entry: transaction manager $get tdt size 

This entry point returns the number of entries allocated in the TDT. 
This number can be used as an upper bound for looping through all TDT 
entries, for example: 

do i = 1 to transact ion_manager_$get_tdt_si ze () ; 
ca 1 1 transact i on_manager_$get_txn_i nf o_i ndex 
(i , txn_i nf o_ptr , code); 

end; 



USAGE 

del transact i on_manager_$get_tdt_s i ze entry returns (fixed bin); number 
= txn_$get_tdt_s i ze () ; 

ARGUMENTS 

x uwi w uiv uw ai guiiiwi us. 



Entry: transaction manager Sget tdt index 

This entry point returns the index of the TDT entry occupied by a specified 
transaction. 

USAGE 

declare transact i on_manager_$get_tdt_i ndex entry (bit (36) aligned, fixed 
bin (35)) returns (fixed bin); 

txn_index = transact i on_manager_$get_tdt_i ndex (txn_id, code); 

ARGUMENTS 

txn_id 

is the identifier of a transaction. (Input) If it is "0"b, the current transaction is 
used. 

code 

is a standard system status code. (Output) It can also be: 

dm_error_$no_current_transaction 

with txn_id = "0"b, no current transaction is defined for this process. 

dm_error_$ transaction_not_f ound 

No transaction exists with the specified transaction identifier. 
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ACCESS REQUIRED 

The caller requires re access to dm_admin_gate_ to obtain the index of another user's 
transaction. 



Entry: transaction manager $get txn__info 

This entry point returns a structure containing all the information in the TDT about a 
transaction. 

USAGE 

declare transact i on_manager__$get_txn_i nfo entry (bit (36) aligned, ptr, 
f i xed bin (35) ) ; 

call transact ion_manager_$get_txn_i nfo (txn_id, txn_i nf o_ptr , code); 

ARGUMENTS 

txn_id 

is the identifier of a transaction, or "0"b to default to the current transaction. 
(Input) 

txn_info_ptr 

is a pointer to the txn_info structure, declared in dm_tm_txn_info.incl.pll. (Input) 

code 

is a standard system status code. (Output) 
ACCESS REQUIRED 

The caller requires re access to dm_admin_gate_ to obtain information about another 
user's transaction. 
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STRUCTURE 



This structure, declared in dm_tm_txn_info.incl.pll, returns information about a 
transaction. 

del 1 txn_info aligned based (txn__i nf o_ptr) , 

2 version char (8) , 

2 txn_id bit (36) aligned, 

2 txn_ index fixed bin, 

2 mode fixed bin, 

2 state fixed bin, 

2 error_code fixed bin (35) » 

2 checkpoi nt_i d fixed bin, 

2 rol 1 back_count fixed bin, 
2 owner_process_id bit (36), 
2 owner_name char (32) , 

2 date_t ime_created fixed bin (71) » 
2 flags, 
3 (dead_process_sw, 

suspended_sw, 

error_sw, 

abandoned_sw, 

kill_sw) bit (1) unaligned, 

3 mbz bit (3D unaligned, 

2 journal_info aligned, 
3 bj_uid bit (36) , 

3 bj_oid bit (36) , 

3 1 ast_compl eted_operat i on 

char (h) , 

3 f i rst_bj_rec_id bit (36), 

3 last_bj_rec_id bit (36), 

3 n_rec_wr i tten fixed bin (35) » 

3 n_bytes_wr i tten fixed bin (35); 



STRUCTURE ELEMENTS 



version 

is the version of the structure, currently TXN_INF0_VERSI0N_5. 
txn_id 

is the identifier of the transaction. 
txn_index 

is the index of the TDT entry for the transaction, 
mode 

is the begin_mode according to which the transaction was begun. See 
transaction_manager_$begin_txn for a list of modes. 
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state 

is one of the states declared in the include file dm_tm_states.incl.pll. It is either 
TM_IN_PROGRESS_STATE for an in-progress transaction, one of several intermediate 
states corresponding to calls made by the transaction manager (usually when the 
owner process has died in the middle of a call to transaction_manager_), or one 
of several error states corresponding to error codes returned by transaction_manager_. 

error_code 

is 0 or an error code returned by the last call made by the transaction manager. 
checkpoint_id 

is the identifier of the checkpoint that has most recently been rolled back to, or 
0 for the start of the transaction. 

rollback_count 

is the number of times that the transaction has been rolled back, either by a 
rollback operation or as part of an unfinished abort 

owner_process_id 

is the identifier of the process that began the transaction. This process may or 
may not still be running. 

owner_name 

is the Person. Project identifier of the process that began the transaction. 

date_time_created 

is the date-time that the transaction was begun. 

dead_process_sw 

is "l"b if the process that began the transaction is no longer running. 

suspended_sw 

is "l"b if the transaction is currently suspended. 

error_sw 

is 'T'b if the transaction manager received an error code from one of its calls 
(error_code A = 0) and the transaction has not been adjusted since. 

abandoned_sw 

is 'T'b if the transaction was abandoned by the owner via a call to 
$abandon_txn. 

kill_sw 

is 'T'b if the owner called $kill_txn and the transaction is therefore waiting to 
be killed. 

bj_uid 

is the UID of the before journal chosen when the transaction was begun. 
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bj_oid 

is the per-process opening identifier of the before journal used by the transaction. 

last_completed_operation 

is the name of the last completed before journal operation. 

first_bj_rec_id 

is the identifier of the first mark for this transaction. 

last_bj_rec_id 

is the identifier of the last mark for this transaction. 
n_rec_written 

is the number of marks that were written for this transaction. 

n_bytes_written 

is the total number of bytes written to the journal. 



This entry point returns the same information as transaction_manager_$get_txn_info but 
accepts the index of a TDT entry rather than a transaction identifier. The transaction 
command, for example, calls this entry ' point with numbers 1 through 
transaction_manager_$get_tdt_size() to print information for the entire TDT. 

USAGE 

declare transact i on_manager_$get_txn_i nfo_i ndex entry (fixed bin, ptr, 
f i xed bin (35) ) ; 

call transact i on_manager_$get_txn_i nfo_i ndex (txn_index, txn_i nf o_ptr , 
code) ; 

ARGUMENTS 

txn_index 

is the index of a TDT entry. (Input) 
txn_info_ptr 

is a pointer to the txn_info structure, declared in dm_tm_txn_info.incl.pll. (Input) 

code 

is a standard system status code. (Output) 
ACCESS REQUIRED 

The caller requires re access to dm_admin_gate_ to obtain information about another 
user's transaction. 
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Entry: transaction manager $handle_conditions 

This entry point, intended to be called by "any_other" handlers in user programs, 
temporarily suspends the current transaction during an interruption caused by a 
signalled condition. When invoked, it suspends the current transaction, allows the 
condition to propagate, and resumes the transaction when control returns. 

USAGE 

declare transact ion_manager_$handle_condi tions entry () ; 
call transact ion_manager_$handle_condi tions () ; 
ARGUMENTS 

There are no arguments. 



Entry: transaction manager Skill txn 

This entry point is intended to be called by the owner of a transaction when the 
owner cannot end the transaction normally and does not want the daemon to try to 
abort it for reasons of efficiency. Killing a transaction can destroy the consistency of 
the databases changed during the transaction, and is therefore appropriate only if 
consistency is no longer an issue (for example, if the databases are to be deleted). As 
with $abandon_txn, calling this entry point frees the user to begin a new transaction. 

USAGE 

declare transact i on_manager_$k i 1 l_txn entry (bit (36) aligned, fixed 
bin (35)); 

call transact i on_manager_$k i 1 l_txn (txn_id, code); 

ARGUMENTS 

txn_id 

is the identifier of the transaction to be killed. (Input) If it is "0"b, the current 
transaction is used. 

code 

is a standard system status code. (Output) It can also be: 

dm_error_$no_current_transaction 

With txn_id="0"b, no current transaction is defined for this process. 

dm_error_$transaction_suspended 

With txn_id="0"b, the current transaction is suspended and therefore cannot 
be killed. 
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ACCESS REQUIRED 

The caller requires re access to dm_admin_gate_. 



Entry: transaction manager $resume txn 

This entry point reactivates a suspended transaction, once again allowing data 
operations on protected files. 

USAGE 

declare transact i on_manager_$resume_txn entry (fixed bin(35))» 

call transact ion_manager_$resume_txn (code); 

ARGUMENTS 

code 

is a standard system status code. (Output) Tt can also be: 

dm_error_$no_current_transaction 

No current transaction is defined for this process. 

dm_error_$no_suspended_transaction 

The current transaction is not suspended. 



Entry: transaction manager Srollback txn 

This entry point rolls the current transaction back to its beginning, by replacing all 
modifications to protected files caused by the transaction, with the before images 
preserved in the appropriate before journal. The transaction remains current for the 
user process. 

USAGE 

declare transact i on_manager_$rollback_txn entry (bit (36) aligned, fixed 
bin, fixed bin (35)) ; 

call transact ion_manager_$rollback_txn (txn_id, checkpoi nt_number , 
code) ; 

ARGUMENTS 

txn_id 

is the identifier of the current transaction, or "0"b to default to the current 
transaction. (Input) If txn_id is neither "0"b nor the transaction identifier of the 
current transaction, dm_error_$transaction_not_current is returned. This argument 
can be used as a check to be sure which transaction is being rolled back. 
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checkpoint_number 

must currently be 0. (Input) 

code 

is a standard system status code. (Output) It can also be: 

dm_error_$no_current_transaction 

No current transaction is defined for this process. 

dm_error_$not_own_transaction 

A process can only roll back its own transaction. 

dm_error_$transaction_suspended 

The current transaction is suspended and therefore cannot be rolled back. 

dm_error_$unf inished_abort 

The transaction was left in the middle of an abort operation. It is possible 
to call $abort_txn to complete the abort, or call either $abandon_txn or 
$kill_txn. 

dm_error_$unf inished_commit 

The transaction was left in the middle of a commit operation. It is possible 
to call $commit_txn to complete the commit, or call either $abandon_txn or 
$kill_txn. 

NOTES 

This entry point will retry rollback of a transaction that was left in an error state by 
a previous rollback. It will not attempt to rollback a transaction left in error by any 
other operation. 



Entry: transaction manager Ssuspend txn 

This entry point puts the current transaction into a suspended state wherein it is 
temporarily unusable. Data operations to protected files are not allowed while the 
transaction is suspended, that is, until $resume_txn is called. Since the suspended 
transaction has not been completed, no new transaction can be begun. 

USAGE 

declare transact i on_manager_$suspend_txn entry (fixed bin(35))» 
call transact ion_manager_$suspend_txn (code); 
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ARGUMENTS 
code 

is a standard system status code. (Output) It can also be: 

dm_error_$no_current_transaction 

No current transaction is defined for this process. 

dm_error_$transactions_suspended 

The current transaction is already suspended. 

NOTES 

Suspension has the following effects: 

1. The current transaction is temporarily unusable. As a result, the entry point 
$get_current_txn_id returns "0"b and the error code 
dm_error_$transaction_suspended. 

2. No data operations on protected files are allowed while the transaction is 
suspended. 

3. Both $begin_txn and $commit_txn return dm_error_$transaction_suspended. 

4. Both $abort_txn and $adjust_tdt_entry (called by DMS) work on suspended 
transactions. 



Entry: transaction manager $user shutdown 

This entry point shuts down DMS in the calling process. All TDT entries belonging to 
the caller's Person. Project are adjusted before DMS is turned off. If the calling 
process is not currently using DMS, the entry does a return. 

Information about the adjusted TDT entries is returned in the structure tm_shutdown_info, 
declared in dm_tm_shutdown_info.incl.pll (see below). 

USAGE 

del transact ion_manager_$user_shutdown entry (ptr, ptr, fixed bin(35))» 

call transact i on_manager_$user_shutdown (area_ptr, tm_shutdown_i nf o_ptr , 
code) ; 
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ARGUMENTS 
area_ptr 

is a pointer to an area in which to allocate the shutdown_info structure. (Input) 

tm„shutdown_inf o_ptr 

is the returned pointer to tm_shutdown_info, found in the 
dm_tm_shutdown_info.incl.pll include file. (Output) 

code 

is a standard system status code. (Output) 
STRUCTURE 

The shutdown_info structure contains information about adjusted TDT entries belonging 
to the calling process and is declared in dm_tm_shutdown.incl.pll. 

del 1 tm_shutdown_i nf o aligned based (tm_shutdown_J nf o_ptr) , 
2 vers ion char (8) , 

2 count fixed bin, 

2 transaction (trn_shutdown_a 1 loc_count refer 

(tn_shutdown_i nfo. count) ) , 
3 txn_id bit (36) aligned, 

3 op_completed fixed bin, 
3 state fixed bin, 

3 error_code fixed bin (35); 

STRUCTURE ELEMENTS 

version 

is the version of the structure, currently TM_SHUTD0WN_INF0_VERSI0N_1. 
count 

is the number of transactions that were adjusted. 
txn_id 

is the identifier of a transaction that was adjusted. 
op_completed 

is equal to one of the constants ABORTED, FINISHED.ABORT, FINISHED.COMMIT, 
or ABANDONED declared in the same include file. 

state 

is the state after adjusting: 0 - a successful adjustment 
error_code 

is the error code returned by adjust; 0 = a successful adjustment. 
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Name: translate aim_attributes 

This subroutine translates the AIM attributes in an authorization or access class from 
one system's defintion to another system's definition if possible. 

USAGE 

declare trans 1 ate_aim__attr ibutes_ entry (ptr, b i t (72) aligned, ptr, 
bit (72) aligned, fixed bin (35)); 

call trans 1 ate_a im_attr i butes__ (source_aim__attr ibutes_ptr, 
source_author i zat ion, target_aim_attr ibutes_ptr , 
target_a im_author i zat i on, code); 

ARGUMENTS 

source_aim_attributes_ptr 

is a pointer to the aim_attributes structure defining the AIM attributes of the 
source system. (Input) This structure is declared in aim_attributes.incl.pll. 

source_aim_authorization 

is the access class or authorization expressed to be translated to the equivalent 
value on the target system. (Input) 

target_aim_attributes_ptr 

is a pointer to the aim_attributes structure defining the AIM attributes of the 
target system. (Input) 

target_aim_authorization 

is set to the access class or authorization on the target system which is equivalent 
to the value given on the source system. (Output) 

code 

is a standard system status code. (Output) It can be one of the following: 
0 

the authorization or access class was successfully translated. 
error_table_$unimplemented_version 

one of the aim_attributes structures supplied by the caller was of a version 

not supported by this procedure. 
error_table_$ai_no_common_max 

there is no set of AIM attributes in common between the two systems. 
error_table_$ai_outside_common_range 

the source access class or authorization is not less than or equal to the 

common access class ceiling between the two systems. 

NOTES 

See the description of the get_system_aim_attributes_ subroutine for a definition of 
the aim_attributes structure. 
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The translation of AIM attributes can only be performed for an authorization or 
access class that is less than or equal to the common access ceiling between the two 
systems. See the Programmers' Reference Manual for a definition of common access 
ceiling. 



Name: translate.. bytes_ 1 _to_hex9_ . 

This entry point translates a bit string to a character string containing the hexadecimal 
representation of the bits. Each 9-bit byte of the input is translated into two hex 
digits by using the low-order (rightmost) 8 bits in each byte. 

USAGE 

declare trans 1 ate_bytes_to_hex9_ entry (bit (<<) , char (*)); 
call trans late_bytes_to_hex9_ (bi t_str i ng, hex_string); 
ARGUMENTS 
bit_string 

is the bit string to be translated. This argument must start on a byte boundary 
and should be a multiple of 9 bit long. Any extra bits, not part of a complete 
byte, are ignored. (Input) 

hex_string 

is the output character string containing hexadecimal digits obtained by translating 
the low-order (rightmost) 8 bits of each 9-bit byte of the input string into 2 hex 
digits. If the output string argument is longer than necessary, then it is filled 
with ASCII "0" characters. (Output) 

NOTES 

This subroutine uses the hardware mvt instruction with a desc4a descriptor for the 
input string and a desc9a descriptor for the output string to do the translation. 
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Name: translator info 

The translator„info„ subroutine contains utility routines needed by the various system 
translators. They are centralized here to avoid repetitions in each of the individual 
translators. 



Entry: translator inf o $get source info 

This entry point returns the information about a specified source segment that is 
needed for the standard object segment storage system location, date-time last 
modified, unique ID. 

USAGE 

declare trans 1 ator_i nf o_$get_source_i nfo entry (ptr, char (*) , char (*) , 
fixed bin (71), bit (36) aligned, fixed bin (35)); 

call trans 1 ator_i nf o_$get_source_i nfo entry (source_ptr, dir_name, 
entryname, date_t imejnod, unique_id, code); 

ARGUMENTS 

source_ptr 

is a pointer to the source segment about which information is desired. (Input) 
dir_name 

is the pathname of the directory in which the source segment is located. (Output) 
entryname 

is the primary name of the source segment. (Output) 
date_time_mod 

is the date-time-modified of the source segment as obtained from the storage 
system. (Output) 

unique_id 

is the unique ID of the source segment as obtained from the storage system. 
(Output) 

code 

is a storage system status code. (Output) 
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NOTES 

Because the interface to this procedure is a pointer to the source segment, the 
presence of a nonzero status code probably indicates that the storage system entry for 
the source segment has been altered since the segment was initiated, i.e., the segment 
has been deleted, or this process no longer has access to the segment 



The entryname returned- by this procedure is the primary name on the source segment 
It is not necessarily the same name as that by which the translator initiated it 



Entry: translator info__ $component__get_source info 

This entry point returns the information about a specified source segment that is 
needed for the standard object segment: storage system location, date-time last 
modified, unique ID. Although there is an argument called component_name, this 
entry point does not currently handle archive components. 

USAGE 

declare trans 1 ator__i nf o__$component_get_source_i nfo entry (ptr, char (*) , 
char (*) , char (*) , fixed bin (71), bit (36) aligned, fixed bin (35)); 

call trans 1 ator_i nf o_$component_get_source_i nfo (source__ptr , di rename, 
entry_name, component_name, date_t ime_mod, unique_id, code) ; 

ARGUMENTS 

source_ptr 

is a pointer to the source segment about which information is desired. (Input) 
dir_name 

is a pathname of the directory in which the source segment is located. (Output) 
entry_name 

is the primary name of the source segment. (Output) 

component_name 

is currently always null. (Output) 

date_time_mod 

is the date_time modified of the source segment as obtained from the storage 
system. (Output) 

unique_id 

is the unique ID of the source segment as obtained from the storage system. 
(Output) 
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code 

is a storage system status code. (Output) 
STATUS CODE 

A status code of zero indicates that all information has been returned normally. 

A nonzero status code returned by this entry is a storage system status code. Because 
the interface to this procedure is a pointer to the source segment, the presence of a 
nonzero status code probably indicates that the storage system entry for the source 
segment has been altered since the segment was initiated, i.e., the segment has been 
deleted, or this process no longer has access to the segment 

NOTES 

The entryname returned by this procedure is the primary name on the source segment. 
It is not necessarily the same name as that by which the translator initiated it. 



Name: translator temp 

This subroutine provides an inexpensive temporary storage management facility for 
translators in the Tools Library. It uses the get_temp_segment_ subroutine to obtain 
temporary segments in the user's process directory. Each segment begins with a header 
that defines the amount of free space remaining in the segment. An entry is provided 
for allocating space in temporary segments, but once allocated, the space can never be 
freed. 



Entry: translator temp Sallocate 

This entry point can be called to allocate a block of space within a temporary 
segment. 

USAGE 

declare trans 1 ator_temp_$al locate entry (ptr, fixed bin) returns (ptr) ; 
Pspace = trans 1 ator_temp_$al locate (Psegment, Nwords) ; 
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ARGUMENTS 
Psegment 

is a pointer to the temporary segment in which space is to be allocated. 
(Input/Output). Psegment must be passed by reference rather than by value, 
because the allocation routine may change its value if there is insufficient space 
in the current temporary segment to perform the allocation. 

Nwords 

is the number of words to be allocated. (Input). It must not be greater than 
sys_inf o_$max_seg_size-32. 

Pspace 

is a pointer to the space that was allocated. (Output). If Nwords > 
sys_info$max_seg_size-32, then Pspace is a null pointer on return. 

NOTES 

As an alternative to calling translator_temp_$allocate, a procedure that must perform 

many allocations can include translator_temp_alloc.incl.pll. This include segment 

contains the program definition of an "allocate" function that can be called like the 

Sallocate entry point above. The allocate function is a quick internal PL1 procedure 

that adds about 60 words to the external procedure and that shares its stack frame. 

Use of the allocate internal procedure can significantly reduce the cost of performing 
many allocations. 



Entry: translator temp $get next segment 

This entry point can be called by a program activation to obtain additional temporary 
segments. 

USAGE 

declare trans 1 ator_temp_$get_next_segment entry (ptr, ptr, 
fixed bin (35)) ; 

call trans 1 ator_temp_$get_next_segment (Psegment, Pnew_segment , code); 

ARGUMENTS 

Psegment 

is a pointer to one of the temporary segments that the program has previously 
obtained during its current activation. (Input) 

Pnew_segment 

is a pointer to the new temporary segment. (Output) 
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code 

is a status code. (Output) 



Entry: translator temp $get segment 

This entry point should be called by each program activation to obtain the first 
temporary segment to be used during that activation. Before the activation ends, the 
program should release the temporary segment for use by other programs. (See the 
translator_temp_$release_all_segments entry point below.) 

USAGE 

declare trans 1 ator_temp_$get_segment entry (char (*) aligned, ptr, 
fixed bin (35)) ; 

call trans 1 ator_temp_$get_segment (program_id, Psegment, code); 

ARGUMENTS 

programed 

is the name of the program that is using the temporary segment (Input). This 
name is printed out by the list_temp_segments command. 

Psegment 

is a pointer to the temporary segment that was created. (Output) 

code 

is a status code. (Output) 



Entry: translator temp Srelease all segments 

This entry point releases all of the temporary segments used by a program activation 
for use by other programs. It truncates these segments to conserve space in the 
process directory. It should be called by each program activation that uses temporary 
segments before the activation is terminated. 

USAGE 

declare trans 1 ator_temp_$rel ease_al l_segments entry (ptr, 
fixed bin (35)) ; 

call trans 1 ator_temp_$rel ease_a 1 l_segments (Psegment, code); 
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ARGUMENTS 
Psegment 

is a pointer to any one of the temporary segments. (Input) 

code 

is a status code. (Output) 
Entry: translator temp $release__segment 

This entry point releases one of the temporary segments used by a program activation. 
It truncates the temporary segment to conserve space in the process directory. 

USAGE 

declare trans 1 ator_temp_$rel ease_segment entry (ptr, fixed bin (35)); 
call trans 1 ator_temp_$re 1 ease_segment (Psegment, code); 
ARGUMENTS 
Psegment 

is a pointer to the temporary segment to be released. (Input) 

code 

is a status code. (Output) 



Name: tssi 

The tssi_ (translator storage system interface) subroutine simplifies the way the 
language translators use the storage system. The tssi_$get_segment and tssi_$get_file 
entry points prepare a segment or multisegment file for use as output from the 
translator, creating it if necessary, truncating it, and setting the access control list 
(ACL) to rw for the current user. The tssi_$finish_segment and tssi_$finish_file entry 
points set the bit counts of segments or multisegment files, make them unknown, and 
put the proper ACL on them. The tssi_$clean_up_segment and tssi_$clean_up_file 
entry points are used by cleanup procedures in the translator (on segments and 
multisegment files respectively). 
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Entry*. tssi_$get_segment 

This entry point returns a pointer to a specified segment. The ACL on the segment is 

rw for the current user. If an ACL must be replaced to do this, aclinfo_ptr is 
returned pointing to information to be used in resetting the ACL. 

USAGE 

declare tss i_$get_segment entry (char (*) , char (*) , ptr, ptr, 
fixed bin(35)) ; 

call tss i_$get_segment (dir_name, entryname, seg_ptr, aclinfo_ptr, 
code) ; 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment (Input) 
seg_ptr 

is a pointer to the segment, or is null if an error is encountered. (Output) 
aclinfo_ptr 

is a pointer to ACL information (if any) needed by the tssi_$finish_segment entry 
point. (Output) 

code 

is a storage system status code. (Output) 



Entry: tssi $get file 

This entry point is the multisegment file version of the tssi_$get_segment entry point. 
It returns a pointer to the specified file. Additional components, if necessary, can be 
accessed using the msf_manager_$get_ptr entry point (see the description of the 
msf_manager_ subroutine), with the original segment considered as component 0. 

USAGE 

declare tss i_$get_f i 1 e entry (char (*) , char (*) , ptr, ptr, ptr, 
fixed bin(35)) ; 

call tss i_$get_f i 1 e (dir_name, entryname, seg_ptr, aclinfo_ptr, fcb_ptr, 
code) ; 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the multisegment file. (Input) 
seg_ptr 

is a pointer to component 0 of the file. (Output) 
aclinfo_ptr 

is a pointer to ACL information (if any) needed by the tssi_$finish_file entry 
point (Output) 

fcb_ptr 

is a pointer to the file control block needed by the msf_manager_ subroutine. 
(Output) 

code 

is a storage system status code. (Output) 



Entry: tssi__$finish_segment 

This entry point sets the bit count on the segment after the translator is finished with 
it It also terminates the segment. If the segment existed before the call to 
tssi_$get_segment, the ACL is reset to the way it was before the tssi_$get_segment 
entry point was called. If no ACL existed for the current user, the mode is set to 
"mode" for the current user. If the segment was created, and the "mode" parameter 
contains the V mode, all entries on the segment's ACL (as derived from the 
containing directory's Initial ACL) receive the "e" bit, as well as the other modes 
specified. The current user, if not specified on the Initial ACL, receives an ACL term 
of "mode" on the segment. Otherwise, the segment's Initial ACL is restored, and, if 
the current user does not have an ACL term, the segment receives an ACL term of 
"mode" for the user. 

USAGE 

declare tss i_$f i n i sh_segment entry (ptr, fixed bin (24), bit (36) aligned, 
ptr , f i xed bin (35) ) 5 

call tss i_$f i ni sh_segment (seg_ptr, be, mode, aclinfo_ptr, code); 
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ARGUMENTS 
seg_ptr 

is a pointer to the segment (Input) 

be 

is the bit count of the segment (Input) 
mode 

is the access mode to be put on the segment. (Input) It can be one of the 
following named constants (declared in access_mode_values.incl.pll): 

"110"b RE_ACCESS 

"101"b RW_ACCESS 

aclinfo_ptr 

is a pointer to the saved ACL information returned by the tssi_$get_segment entry 
point (Input) 

code 

is a storage system status code. (Output) 



Entry: tssi $finish file 

This entry point is the same as the tssi_$finish_segment entry point, except that it 
works on multisegment files, and closes the file, freeing the file control block. 

USAGE 

declare tss i_$f i ni sh_f i 1 e entry (ptr, fixed bin, fixed bin (2*0, bit (36) 
aligned, ptr, fixed bin(35)); 

call tssi_$f inish_f i le (fcb_ptr, component, be, mode, aclinfo_ptr, 
code) ; 

ARGUMENTS 

fcb_ptr 

is a pointer to the file control block returned by the tss i_$get_file entry point. 
(Input) 

component 

is the highest-numbered component in the file. (Input) 

be 

is the bit count of the highest-numbered component. (Input) 
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mode 

is the access mode to be put on the multisegment file. (Input) It can be one of 
the following named constants (declared in access_mode_values.incl.pll): 

"110"b RE.ACCESS 

"lOr'b RW_ACCESS 

aclinfo_ptr 

is a pointer to the saved ACL information returned by the tssi_$get_file entry point. (Input) 

code 

is a storage system status code. (Output) 



Entry: tssi $clean__up_segment 

Programs that use the tssi_ subroutine must establish a cleanup procedure that calls 
this entry point (For a discussion of cleanup procedures see the Programmer's 
Reference Manual.) If more than one call is made to the tssi_$get_segment entry 
point, the cleanup procedure must make the appropriate call to the tssi_$clean_up_segment 
entry point for each acliiifo_pir. 

The purpose of this call is to free the storage that the tssi_$get_segment entry point 
allocated to save the old ACLs of the segments being translated. It is to be used in 
case the translation is aborted (e.g., by a quit signal). 

USAGE 

declare tss i $c 1 ean_up_segment entry (ptr) ; 

call tss i_$c 1 ean_up_segment (ac 1 i nf o_ptr) ; 
ARGUMENTS 

vr\ir>fr\ ntr 

is a pointer to the saved ACL information returned by the tssi_$get_segment entry 
point. (Input) 



Entry: tssi $clean up file 

This entry point is the cleanup entry point for multisegment files. In addition to 
freeing ACLs, it closes the file, freeing the file control block. 

USAGE 

declare tss i_$cl ean_up_f i 1 e entry (ptr, ptr); 
call tssi_$clean_up_f i le (fcb_ptr, ac 1 i nf o_ptr) ; 
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ARGUMENTS 
fcb_ptr 

is a pointer to the file control block returned by the tssi_$get_file entry point 
(Input) 

aclinfo_ptr 

is a pointer to the saved ACL information returned by the tssi_$get_segment entry 
point. (Input) 



Name: total cpu time 

The total_cpu_time_ subroutine returns the total CPU time used by the calling process 
since it was created. The time includes time spent handling page faults, segment faults, 
and bound faults for the calling process as well as time spent handling any system 
interrupt that occurred while the calling process was executing. 

USAGE 

declare total_cpu_time_ entry returns (fixed bin (7D); 

time = total _cpu_time_ () ; 

ARGUMENTS 

time 

is the total CPU time, in microseconds, used by the calling process. (Output) 



Name: ttt info 

The ttt_info_ subroutine extracts information from the terminal type table (TTT). 
Entry: ttt info Sadditional info 

This entry point returns additional information for a specified terminal type to be 
used by I/O modules other than tty_. 

USAGE 

declare ttt_i nf o_$add i t i onal_i nf o entry (char (*) , char (*) varying, 
fixed bin (35)) ; 

call ttt info_$addi tional_info (tt_name, add_info, code); 
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ARGUMENTS 



tt_name 

is the terminal type name. (Input) 



add_info 

is the additional information string. (Output). If no additional information is 
defined for the terminal type, a null string is returned. Maximum length is 512 
characters. 



code 

is a standard status code. (Output) 



Entry: ttt info Sdecode answerback 

This entry point decodes a specified answerback string into a terminal type name and 
terminal identifier. 

declare ttt_i nf o_$decode_answerback entry (char (*) , fixed bin, char (*) , 
char (*) , fixed bin (35)) ; 

call ttt_i nf o_$decode_answerback (ansb, line_type, tt_name, id, code); 

ARGUMENTS 

ansb 

is the answerback string. (Input) 
line_type 

is a line type number with which the decoded terminal type must be compatible. 
(Input). A nonpositive line type number is ignored. For further description, see 
the tty_ I/O module. 

tt_name 

is the terminal type name decoded from the answerback. (Output). Its length 
should be at least 32 characters. If no terminal type is indicated, a null string is 
returned. 

id 

is the terminal identifier decoded from the answerback. (Output). Its length 
should be at least four characters. If no id is indicated, a null string is returned. 

code 

is a standard status code. (Output) 
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Entry: tt t_i nf o_$deeode_ty pe 

This entry point obtains the terminal type name that corresponds to a specified 
terminal type code number. 

USAGE 

declare ttt_i nf o_$decode_type entry (fixed bin, char (*) , fixed bin (35)); 

call ttt_i nf o_$decode_type (type_code, tt_name, code); 

ARGUMENTS 

type_code 

is the terminal type code number. (Input) 
tt_name 

is the corresponding terminal type name. (Output) 

code 

is a standard status code. (Output) 



Entry: ttt info Sdialup flags 

This entry point returns the values of two flags for a specified terminal type. 
USAGE 

declare ttt_i nf o_$di alup_f lags entry (char (*) , bit(l), bit(l), 
fixed bin (35)) ; 

call ttt_info_$dialup_f lags (tt_name, ppm__flag, cpo_flag, code); 

ARGUMENTS 

tt_name 

is the terminal type name. (Input) 
ppm_flag 

indicates whether a preaccess message should be printed when an unrecognizable 
login line is received from a terminal of the specified type (Output): 
"l"b yes 
"0"b no 
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cpo_flag 

indicates whether "conditional printer off" is defined for the terminal type; i.e., if 
the answerback indicates whether a terminal is equipped with the printer off 
feature (Output): 
"l"b yes 
"0"b no 

code 

is a standard status code. (Output) 



Entry: ttt info $encode type 

This entry point obtains a code number that corresponds to a specified terminal type 
name. 

USAGE 

declare ttt_i nf o_$encode_type entry (char (*) , fixed bin, fixed bin (35)); 

call ttt_i nf o_$encode_type (tt_name, type_code, code); 

ARGUMENTS 

tt_name 

is the terminal type name. (Input) 
type_code 

is the corresponding terminal type code number. (Output) 

code 

is a standard status code. (Output) 



Entry: ttt info $function_key data 

This entry point returns a collection of information describing the function keys of a 
specified terminal type. 

USAGE 

del ttt_i nfo_$funct i on_key_data entry (char (*) , ptr, ptr, 
fixed bin (35)) ; 

call ttt_i nfo_$f unct ion_key_data (tt_name, areap, f unct i on_key_data_ptr , 
code) ; 
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ARGUMENTS 
tt_name 

is the terminal type name. (Input) 
areap 

points to an area where the function_key_data info structure can be allocated. 
(Input). If null, the system free area is used. If the area is not large enough, 
the area condition is signaled. 

f unction_key_data_ptr 

points to the function_key_data structure allocated by this entry point. (Output). 
The structure is described below. 

code 

is a standard system status code. (Output) 
DATA STRUCTURE 

The data structure allocated by this routine is declared in the include file 
f unction_key_data.incl.pll. 

del 1 f unct i on_key_data aligned based (f unct i on_key_data_ptr) , 
2 version fixed bin, 
2 highest fixed bin, 
2 sequence, 

3 seq_ptr pointer, 

3 seq_len fixed bin (21), 
2 cursor_mot i on_keys , 

3 home (0:3) like key_info, 

3 left (0:3) like key_info, 

3 up (0:3) like key_info, 

3 right (0:3) like key_info, 

3 down (0:3) like key_info, 
2 f unct i on_keys (0: f unct i on_key_data_h i ghest refer 
(f unct ion_key_data. highest) , 0:3) like key_info; 

del (KEY_PLA I N ini t (0) , 
KEY_SH I FT init (1) , 
KEY_CTRL init (2) , 
KEY_CTRL_AND_SH I FT init (3)) 
fixed bin internal static options (constant); 

del 1 key_info unaligned based (key_i nf o_ptr) , 

2 sequence_i ndex fixed bin (12) unsigned unaligned, 
2 sequence_l ength fixed bin (6) unsigned unaligned; 
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STRUCTURE ELEMENTS 
version 

is the version of this structure. It should be set to function_key_data_version_l. 
highest 

is the number of the highest function key defined, 
sequence 

defines the character string holding the concatenation of all the sequences. The 
sequence for a given key is defined as a substring of this string. 

seq_ptr 

is the address of the string. 

seq_len 

is its length. 

cursor_motion_keys 

defines some miscellaneous keys whose names connote motion of the cursor. Note 
that the meaning of these keys is defined only by the application, which may or 
may not choose to take advantage of the mnemonic value of these key legends. 

home 

defines the sequences for the HOME key, used by itself, with SHIFT, with 
CONTROL, and with SHIFT and CONTROL. An absent sequence has a sequence 
length of zero. 

left 

defines the left arrow key in the same way as HOME is defined. 

up 

defines the up-arrow key. 

right 

defines the right-arrow key. 
down 

defines the down-arrow key. 
function_keys 

defines the sequences for the function keys of the terminal. If the terminal has 
no function key labelled "0", all sequences for 0 have zero length. 

key_info 

defines a given sequence. 
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sequence_index 

is the index of the beginning of the sequence in the string of all sequences, 
sequencejength 

is the length of the sequence. If zero, the sequence is not present 
NOTES 

Mnemonic values are defined for the subscripts for various key combinations: 
KEY_PLAIN, KEY.SHIFT, KEY_CTRL, and KEY_CTRL_AND_SHIFT. For example, 
the sequence for the left-arrow key with SHIFT is: 

substr (f unction_key__seqs, 

f unct ion_key_data. left (KEY_SHI FT) .sequence_of f set, 
f unction_key_data. left (KEY_SHI FT) . sequence_l ength) 



Entry: ttt info $initial___string 

This entry point returns a string that can be used to initialize terminals of a specified 
terminal type. The string must be transmitted to the terminal in raw output (rawo) 
mode. The initial string is most commonly used to set tabs on terminals that support 
tabs set by software. 

USAGE 

declare ttt__i nf o_$ i ni t i al_str i ng entry (char (*) , char (*) varying, 
fixed bin (35)) ; 

call ttt_i nf o_$ i ni tial_string (tt_name, istr_info, code); 
ARGUMENTS 
tt_name 

is the terminal type name. (Input) 
istr_info 

is the initial string. (Output). If no initial string is defined for the terminal type, 
a null string is returned. Maximum length is 512 characters. 

code 

is a standard status code. (Output) 



2-903 



AG93-05 



ttt_info_ 



ttt_info_ 



Entry: ttt info Smodes 

This entry point returns the default modes for a specified terminal type. 
USAGE 

declare ttt_i nf o__$modes entry (char (*) , char (*) , fixed bin (35)); 

call ttt_i nf o_$modes (tt_name, modes, code); 

ARGUMENTS 

tt_name 

is the terminal type name. (Input) 
modes 

is the default modes string for the terminal type. (Output). If its length is less 
than 256 characters, the entire modes string is not necessarily returned. 

code 

is a standard status code. (Output) 



Entry: ttt info $preaccess type 

This entry point returns the terminal type name associated with a specified preaccess 
request. 

USAGE 

declare ttt_i nf o_$preaccess_type entry (char (*) , char (*) , 
f i xed bin (35) ) ; 

call ttt_i nf o_$preaccess_type (request, tt_name, code)); 

ARGUMENTS 

request 

is one of the following three preaccess requests: MAP, 963, or 029. (Input) 
tt_name 

is the name of the associated terminal type. (Output). Its length should be at 
least 32 characters. 

code 

is a standard status code. (Output) 
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Entry: ttt__info__$terminal_data 

This entry point returns a collection of information that describes a specified terminal 
type. 

USAGE 

declare ttt_i nf o_$termi nal_data entry (char (*) , fixed bin, fixed bin, 
ptr , fixed bin (35) ) ; 

call ttt_i nf o_$termi nal_data (tt_name, line_type, baud, ttd_ptr, code); 

ARGUMENTS 

tt_name 

is the terminal type name. (Input) 
line_type 

is a line type number against which the compatibility of the terminal type is 
verified. (Input). If nonpositive, the line type number is ignored. For further 
description, see the tty_ I/O module. 

baud 

is a baud rate used to select the appropriate delay table. (Input) 
ttd_ptr 

is a pointer to a structure in which information is returned. (Input). (See "Notes" 
below.) 

code 

is a standard status code. (Output). If the terminal type is incompatible with the 
line type, a value of error_table_$incompatible_term_type is returned. 
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NOTES 

The ttd_ptr argument should point to the following structure (terminal_type_data.incl.pll): 
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STRUCTURE ELEMENTS 
version 

is the version number of the above structure. (Input). It must be 1 or 2. 
old_type 

is the old terminal type number that corresponds to the terminal type name. 
(Output). (The old terminal type number is provided only for compatibility with 
the obsolete set_type and info tty_ order requests.) A value of -1 indicates that 
no corresponding old type exists. 

name 

is the terminal type name. (Output) 
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input_tr_ptr 

is a pointer to a structure containing the input translation table. (Output). This 
structure is identical to the info structure for the set_input_translation order of 
the tty_ I/O module. 

output_tr_ptr 

is a pointer to a structure containing the output translation table. (Output). This 
structure is identical to the info structure for the set_output_translation order of 
the tty_ I/O module. 

input_cv_ptr 

is a pointer to a structure containing the input conversion table. (Output). This 
structure is identical to the info structure for the set_input_con version order of 
the tty_ I/O module. 

output_cv_ptr 

is a pointer to a structure containing the output conversion table. (Output). This 
structure is identical to the info structure for the set_output_con version order of 
the tty_ I/O module. 

special_ptr 

is a pointer to a structure containing the special characters table. (Output). This 
structure is identical to the info structure for the set_special order of the tty_ 
I/O module. 

delay_ptr 

is a pointer to a structure containing the delay table. (Output). This structure is 
identical to the info structure for the set_delay order of the tty_ I/O module. 

erase 

is the erase character. (Output) 

kill 

is the kill character. (Output) 

frame_begin 

is the frame-begin character. (Output) 

frame_end 

is the frame-end character. (Output) 

keyboard_iocking 

indicates whether the terminal type requires keyboard locking and unlocking. 
(Output) 
"l"b yes 
"0"b no 

input_timeout 

is "l"b if the timeout option was specified on an input_resume statement in the 
TTF. (Output) 
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output_block_acknowledge 

is "l"b if output_end_of_block and output_acknowledge statements were specified 
in the TTF. (Output) 

mbz 

must be "0"b. 

line_delimiter 

is the line delimiter character. (Output) 

The remaining elements are not present if version (above) is 1. 

flow_control_chars 

identifies the flow control characters. 

input_suspend 

is the character sent to the terminal to suspend input, or sent by the terminal to 
indicate that it is suspending input. (Output) 

input_resume 

is the character sent to the terminal to resume input. (Output) 
output_suspend_etb 

is the character sent by the terminal to suspend output if output_block_acknowledge 
is "0"b; otherwise, it is the character to be appended to each output block. 
(Output) 

output_resume_ack 

is the character sent by the terminal to resume output if output_block_acknowledge 

is "0"b; otherwise, it is the character used to acknowledge an output block. 
(Output) 

uuljjui uui i ta oi^c 

is the size, in characters, of the terminal's buffer, for use with a block 

acknowledgement protocol. (Output). It is 0 unless output_block_acknowledge is 
"l"b. 



Entry: ttt info__$video_info 

This entry point is used to obtain a copy of the video sequences table for a particular 
terminal type. 
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USAGE 



declare ttt_i nf o_$vi deo_i nf o entry (char (*) , fixed bin, ptr, ptr, 
fixed bin(35)) ; 

call ttt_info_$video_info (termi nal_type, baud_rate, areap, 
tty_vtbl_ptr , code) ; 

ARGUMENTS 

terminal_type 

is the name of the terminal type for which the video table is required. (Input) 



is the current baud rate of the terminal. (Input). This can be set to 0 if it is 



is a pointer to an area where the video table may be allocated. (Input). If null, 
the system free area is used. 

tty_vtbl_ptr 

is a pointer to the video table, if present. (Output) 

code 

is a standard system status code. (Output) 



The format of a video table is given in the include file tty_video_tables.incl.pll. 



baud_rate 



unknown. 



area 



NOTES 



del 1 tty_video_table 



2 version 

2 screen_he i ght 

2 screen 1 ine_length 

2 scrol l_count 
2 flags 



3 pad 
2 video_chars_i en 
2 pad 
2 nseq 
2 sequences 



2 



video chars 



3 overstr i ke_avai lable 
3 automat i c_cr 1 f 
3 simulate_eol 



aligned based (ttyvtblp), 

fixed bin, 

f i xed bin, 

fixed bin, 

fixed bin, 

unal i gned , 

bit (1) unal, 

bit (1) unal, 

bit (1) unal , 

bi t (33) unal i gned, 

fixed binary (21) 

(2) bin (36) 

fixed bin, 

(N_VIDEO_SEQUENCES refer (tty_video_tabl e.nseq) ) 

like tty_video_seq aligned, 
char (tty_video_table_video_chars_len refer 

(tty_video_table.video_chars_len) ) unal ; 



2-909 



AG93-05 



ttt_info. 



ttt_info_ 



STRUCTURE ELEMENTS 
version 

is the version of this structure. It must be tty_video_tables_version_l, also 
declared in this include file. 

screen_height 

is the number of lines on this terminal. 

screen_line_length 

is the number of character positions (columns) in each line. 

scroll_count 

is the number of lines scrolled upward when a scroll command is sent to the 
terminal (if the terminal is capable of scrolling). For most terminals this will be 
1. A value of 0 indicates that one line is scrolled. 

flags 

describe characteristics of the terminal. 
overstrike_available 

is "l"b if the terminal can overstrike (i.e., more than one character can be seen 
in the same character position). 

automatic_crlf 

is "l"b if the terminal performs a carriage return and line feed when a character 
is displayed in the last column. 

simulate_eol 

is reserved for future expansion. 

pad 

has an undefined value, and is reserved for future expansion. 
video_chars_len 

specifies the length of the string containing all video sequences. 

pad 

is reserved for future expansion. 

nseq 

is the number of the highest video sequence defined for this terminal. Not all 
sequences are defined for all terminals, so programs should check this value 
before indexing the sequence array. 
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sequences 

is an array of video sequences. Each element of the array specifies the character 
sequence for a video control operation. The indices for specific sequences are 
defined by constants also declared in this include file. See below. 

video_chars 

is a string holding concatenations of all video sequences. 

The include file defines values for the indices into the array of sequences for the 
video operations supported. The names of these values are: ABS_POS, CLEAR_SCREEN, 
CLEAR_TO_EOS, HOME, CLEAR_TO_EOL, CURSOR.UP, CURSOR_RIGHT, 
CURSOR_DOWN, CURSOR_LEFT, INSERT.CHARS, END_INSERT_CHARS, 
DELETE_CHARS, INSERT_LINES, DELETE.LINES. The include file also defines 
N_VIDEO_SEQUENCES, which is the number of the highest index ever defined. 

A video sequence is defined by the tty_video_seq structure in the include file 
tty_video_tables.incl.pll. 

del 1 tty_vi deo_seq based (ttyvseqp) aligned, 



f 1 ags 

3 present 

3 interpret 

3 abl e_to_repeat 

3 cpad_present 

3 cpad_i n_chars 

3 pad 

3 general 

cpad 

pad 

len 

seq_i ndex 



unal i gned, 



bit 
bit 
bit 
bit 
bit 
bit 
bit 



) unal , 

) unal, 

) unal, 

) unal, 

) unal, 

7) unal i gned, 

6) unal i gned, 

uns i gned una 1 i gned , 



fixed bin (18) 
bit (15) unal, 

fixed bin (9) unsigned unaligned, 
fixed bin (12) unsigned unaligned; 



STRUCTURE ELEMENTS 



present 

is "l"b if the operation is supported. 



interpret 

is "l"b if the sequence contains the encoding of the line, column, or repeat count 
and must be inspected more closely. 

able_to_repeat 

is 'T'b if the terminal can perform multiple sequences of this operation by 
receiving a single-character sequence containing the repeat count that is encoded 
in the sequence. 

cpad_present 

is 'T'b if the terminal requires padding after the operation. 
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cpad_in_chars 

is "l"b if the padding is in characters, or M 0"b if the padding is in tenths of 
milliseconds. If the baud rate is supplied to the ttt_info_$video_info subroutine, 
then padding is always expressed in characters. 



pad 

is reserved for future expansion. 



general 

is reserved for future expansion to define per-sequence information. 

cpad 

is the padding count in units defined by cpad_in_chars. 



pad 

is reserved for future expansion. 



len 

is the length of the string of characters defining this sequence. 
seq_index 

is the index of the start of the string in tty_video_table.video_chars. 

Many terminals allow a repetition count to be supplied with an operation (e.g., to 
delete multiple lines). Positioning operations require line and column coordinates. 
These values must be expressed in some encoding. A variety of encodings are 
supported. Parameters to be transmitted are specified by an encoding character in the 
video sequence string. An encoding character is a nine-bit byte whose high order bit 
is set and is defined by the structure tty_numeric_encoding in the include file 
tty_video_tables.incl.pll. The encoding scheme is described in the write-up for the 
video_info table of the Terminal Type file in the Programmer's Reference Manual. 

del 1 tty_numer i c_encod i ng based unaligned, 
2 flags, 

3 must_be_on bit (1) unal, 

3 express_i n_decimal bit (1) unal, 

3 express_i n_octa 1 bit (1) unal, 

3 offset_is_0 bit (1) unal, 

2 l_c_or_n fixed bin (2) unsigned unaligned, 

2 num_digits fixed bin (2) unsigned unaligned, 

2 pad bit (1) unaligned 

2 offset fixed bin (8) unaligned; 



STRUCTURE ELEMENTS 

must_be_on 

is "l"b for an encoding character. 



express_in_decimal 

is "r'b if the value should be expressed as decimal digits. 
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express_in_octal 

is "l"b if the value should be expressed in octal digits. If both flags are off, the 
value should be sent as a single character. 

offset_is_0 

if "0"b, the following byte is a fixed bin(8) value to be added to the value 
before encoding. If 'T'b, the offset is 0, and the next byte has no special 
significance. 

l_c_or_n 

specifies the type of value to be encoded. Its value can be 0, 1, or 2, and 
indicates that this encoding character specifies the line number, column number, 
or repeat count, respectively. 

num_digits 

specifies the number of digits to be sent A value of 0 causes all significant 
digits to be sent, with leading zeroes suppressed. 

pad 

is reserved for future expansion, 
offset 

is present only if offset_is_0 is "0"b. It gives an offset to be added to the value 
before expressing it in octal or decimal. 



Name: unique bits 

The unique_bits_ function returns a bit string that is useful as an identifier. It is 
obtained by reading the system clock, which returns the number of microseconds 
elapsed since January 1, 1901, 0000 hours Greenwich mean time. The bit string is, 
therefore, unique among all bit strings obtained in this manner in the history of this 
Multics installation. 

USAGE 

declare unique_bits_ entry returns (bit (70)); 

bit_string - unique_bits_ 0; 

ARGUMENTS 

bit_string 

is the unique value. (Output) 
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Name: unique chars 

The unique_chars_ function provides a character-string representation of a bit string. 
If the bit string is supplied by the unique_bits_ subroutine, this character string is 
unique among all character strings generated in this manner in the history of this 
Multics installation and is therefore useful as an identifier. 

USAGE 

declare unique_chars_ entry (b i t (*) ) returns (char (15)); 

char_string = unique_chars_ (bits); 

ARGUMENTS 

char_string 

is a unique character string. (Output) 

bits 

is a bit string of up to 70 bits. (Input) See "Notes" below. 
NOTES 

If the bits argument is less than 70 bits in length, unique_chars_ pads it with zeros 
on the right to produce a 70-bit string. If the bits argument equals zero, 
unique_chars_ calls unique_bits_ to obtain a unique bit string. 

The first character in the character string produced is always an exclamation point to 
identify the string as a unique identifier. The remaining 14 characters that form the 
unique identifier are alphanumeric, excluding vowels. 



Entry: unique chars Sbits 

This entrypoint converts a unique character string to its bit string representation. 
USAGE 

declare un i que_chars_$b i ts entry (char(15)) returns (bit (70)); 

bits = unique_chars_$bi ts (char_str i ng) ; 

ARGUMENTS 

bits 

is a bit string representation of the unique char_string. (Output) 
char_string 

is a unique character string to be converted to a bit string. (Input) 
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Name: unwinder 

The unwinder_ subroutine is used to perform a nonlocal goto on the Multics stack. It 
is not intended to be called by direct programming (i.e., an explicit call statement in 
a program) but rather, by the generated code of a translator. For example, it is 
automatically invoked by a PL/I goto statement involving a nonlocal label variable. 

When invoked, the unwinder_ subroutine traces the Multics stack backward until it 
finds the stack frame associated with its label variable argument or until the stack is 
exhausted. In each stack frame it passes, it invokes the handler (if any) for the 
cleanup condition. When it finds the desired stack frame, it passes control to the 
procedure associated with that frame at the location indicated by the label variable 
argument. If the desired stack frame cannot be found or if other obscure error 
conditions arise (e.g., the stack is not threaded correctly), the unwinder_ subroutine 
signals the unwinder_error condition. If the target is not on the current stack, and 
there is a stack in a higher ring, that stack is searched after the current one is 
unwound. 

USAGE 

declare unwinder_ entry (label); 
call unwinder_ (tag); 
ARGUMENTS 
tag 

is a nonlocal label variable. (Input) 



Name: user info 

The user_info_ subroutine allows the user to obtain information concerning his login 
session. All entry points that accept more than one argument count their arguments 
and only return values for the number of arguments given. 

The user_info_ entry point returns the user's login name, project name, and account 
identifier. 

USAGE 

declare user_i nf o_ entry (char (*) , char (*) , char(*)); 
call user_info_ (person_id, project_id, acct) ; 
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ARGUMENTS 
person_id 

is the user's name from the login line (maximum of 22 characters). (Output) 
projected 

is the user's project identifier (maximum of 9 characters). (Output) 

acct 

is the user's account identifier (maximum of 32 characters). (Output) 



Entry: user info Sabsentee queue 

This entry point returns the queue number of the absentee queue for an absentee 
process. For an interactive process, the number returned is -1. 



call user_i nf o_$absentee_queue (queue); 

ARGUMENTS 

queue 

is the number of the absentee queue. (Output) 
Entry: user inf o__$absentee request_id 

This entry point returns the identifier by which the absentee request is known to the 
absentee user manager. This is the ID which is used by the absentee request 



declare user_i nf o_$absentee_request_i d entry (fixed bin(70); 
call user_i nf o_$absentee_request_i d (requested) ; 
ARGUMENTS 
requested 

is the request ID corresponding to this absentee process. (Output) For an 
interactive or daemon process, the request_id returned is 0. 



USAGE 





USAGE 
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Entry: user_info__$absentee._restarted 

This entry point returns a bit indicating whether this absentee process has been 
restarted after a system crash. 

USAGE 

declare user_info_$absentee_restar ted (bit(l) aligned); 
call user_info_$absentee_restarted (restarted_bi t) ; 
ARGUMENTS 
restarted_bit 

is on if the absentee job has been restarted after a system crash. 
NOTES 

If this absentee process was restarted after a system crash, and the absout_truncation 
bit is on, truncation will not be performed. See user_info_$absout_truncation. 

Entry: user__info_$absin 

This entry point returns the pathname of the absentee input segment for an absentee 
job. For an interactive user, the pathname is returned as blanks. 

USAGE 

declare user_i nfo_$absi n entry (char(*)); 
call user_info_$absin (path); 
ARGUMENTS 
path 

is the pathname of the absentee input segment (maximum of 168 characters). 
(Output) 
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Entry: user_info_$absout 

This entry point returns the pathname of the absentee output segment for an absentee 
job. For an interactive user, the pathname is returned as blanks. 

USAGE 

declare user_i nf o_$absout entry (char(*)); 
call user_i nf o_$absout (path); 
ARGUMENTS 
path 

is the pathname of the absentee output segment (maximum of 168 characters). 
(Output) 

Entry: user__info Sabsout truncation 

This entry point returns a bit indicating whether this absentee process had the 
-"truncate absout file argument requested. 

USAGE 

declare user_i nf o_$absout_truncat ion (bit(l) aligned); 
call user_i nf o_$absout_truncat ion (truncate_bi t) ; 
ARGUMENTS 
truncate_bit 

is "a"b if the -truncate argument was used for the request that created this 
absentee process; "0"b if not. See Notes. 

NOTES 

If the absentee process has been restarted after a system crash, and the truncate bit is 
set, truncation will not be performed. See user_info_$absentee_restarted. 
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Entry: user_info {attributes 

This entry point returns a character string containing the name of the user's attributes, 
each separated by a comma and a space, and ending in a semicolon. Attributes control 
such things as the ways in which the user may log in, and the arguments that he is 
permitted to give when logging in. They are assigned by the project or system 
administrator. Login attributes are defined in the MAM Project Administrator's 
manual. 

USAGE 

declare user_i nf o_$attr ibutes entry (char (*) varying); 

call user_i nfo_$attr ibutes (attr) ; 

ARGUMENTS 

attr 

is the string containing the names of the user's attributes. (Output) 
Entry: user_.inf o {authorization range 

This entry point returns the range of authorizations at which the calling user may 
create a process. 

USAGE 

declare user_i nf o_$au thor i zat i on_range entry ((2) bit (72) aligned); 

call user_i nf o_$author izat ion_range (auth_range) ; 

ARGUMENTS 

auth_range 

represents the range of authorizations at which the user may log in. 
Entry: user_Jnfo Shomedir 

This entry point returns the pathname of the user's initial working directory. 
USAGE 

declare user_i nfo_$ homed i r entry (char (*) ) ; 
call user info $homedir (hdir); 
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ARGUMENTS 
hdir 

is the pathname of the user's home directory (maximum of 64 characters). 
(Output) 



Entry: user info Slimits 

This entry point returns the limit values established for the user by the project 
administrator and also returns the user's spending against these limits. 

If a limit is specified as open, the limit value returned is 1.0e37. 
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USAGE 

declare user_i nf o_$ 1 imi ts entry (float bin, float bin, fixed bi n (71) , 
fixed bin, (0:7) float bin, float bin, float bin, 
(0:7) float bin) ; 

call user_i nf o_$ 1 imi ts (ml im, cl im, cdate, erf, shlim, msp, csp, shsp) ; 

ARGUMENTS 

mlim 

is the dollar amount the user can spend in the month. (Output) 

clim 

is the dollar amount the user can spend (cutoff limit). (Output) 
cdate 

is the cutoff date. (Output) 

erf 

is the cutoff refresh code. (Output) This indicates what happens at the cutoff 
date: 

0 permanent cutoff 

1 add one day 

2 add one month 

3 add one year 

4 add one calendar year 

5 add one fiscal year 

shlim 

is an array that shows the dollar amount the user can spend per shift. (Output) 

msp 

is the month-to-date spending in dollars. (Output) 

csp 

is the spending against the cutoff limit in dollars. (Output) 

shsp 

is the array of spending against shift limits in dollars. (Output) 
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This entry point returns load control information for the user. 
USAGE 

declare user_i nf o_$ load_ct l_i nf o entry (char (*) , fixed bin, 
fixed bin (71), fixed bin); 

call user_i nfo_$ load_ct l_i nf o (group, stby, preempt_t ime, weight); 

ARGUMENTS 

group 

is the name of the load control group. (Output) 

stby 

indicates whether a user is a standby user (i.e., one who can be preempted). 
(Output) 

i can be preempted 
0 cannot be preempted 

preempt_time 

is the clock time after which the user becomes standby. (Output) 
weight 

is 10 times the user's weight. (Output) Weight is a measure of the load placed on 
the system by the user; most users have a weight of 1. 

Entry: user info Slogin arg count 

This entry point returns the number of arguments which were provided to the process 
by the command responsible for the creation of the process. For an absentee process, 
arguments are given to the enter_abs_request command, using the control argument 
-arguments. For interactive and daemon processes, arguments are specified on the 
login command line, also using the control argument -arguments. 

USAGE 

declare user_i nf o_$ 1 og i n_arg_count entry (fixed bin, fixed bin (21), 
fixed bin (21)) ; 

call user_i nfo_$ logi n_arg_count (count, max_length, total_l ength) ; 
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ARGUMENTS 
count 

is a number representing the number of arguments supplied by the command 
which caused the process creation. (Output) 

max_length 

is the length of the longest login argument. (Output) 
total_length 

is the total length of all the login arguments. (Output) 



Entry: user info Slogin arg ptr 

This entry point returns a pointer to the character-string login argument specified by 
the argument number, and also returns the length of the argument-string. See the 
description of user_info_$login_arg_count for more information about login arguments. 

USAGE 

declare user_i nf o__$ 1 og i n_arg__ptr entry (fixed bin, ptr, fixed bin (21), 
f i xed bin (35) ) ; 

call user_i nfo_$ logi n_arg_ptr (arg_no, arg_ptr, arg_len, code); 

ARGUMENTS 

arg_no 

is an integer specifying the number of the desired argument. (Input) 
arg_ptr 

is a pointer to the unaligned character-string argument specified by arg_no. 
(Output) 

argjen 

is the length (in characters) of the argument specified by arg_no. (Output) 

code 

is a standard status code. (Output) If the code error_table_$noarg is returned, the 
values of arg_ptr and arg_len are undefined. 
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Entry: user info Slogin data 

This entry point returns useful information about how the user logged in. 
USAGE 

declare user_info_$login__data entry (char (*) , char (*) , char (*) , 
fixed bin, fixed bin, fixed bin, fixed bin(7D» char (*) ) ; 

call user_i nf o_$ logi n_data (person_id, project_id, acct, anon, stby, 
weight, time_login, login_word); 

ARGUMENTS 

person_id 

is the user's name from the login line (maximum of 22 characters). (Output) 
projected 

is the user's project identifier (maximum of 9 characters). (Output) 

acct 

is the user's account identifier (maximum of 32 characters). (Output) 

anon 

indicates whether a user is an anonymous user. (Output) 
1 is anonymous 

0 is not anonymous 

stby 

indicates whether a user is a standby user (i.e., one who can be preempted). 
(Output) 

1 can be preempted 

0 cannot be preempted 

weight 

is 10 times the user's weight. (Output) See the user_info_$load_ctl_info entry 
point. 

time_login 

is the time the user logged in. (Output) It is expressed as a calendar clock 
reading in microseconds. 

login_word 

is "login" or "enter," depending on which command was used to log in. (Output) 
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Entry: user__info__$logout data 

This entry point returns information about how the user logs out. 
USAGE 

declare user_info__$logout_data entry (fixed bin (71) » bit (36) aligned); 
call user_i nf o_$ logout_data (1 ogout_channel , logout_pid) ; 
ARGUMENTS 
logout_channel 

is the event channel over which logouts are to be signalled. (Output) 
logout_pid 

is the process identifier of the answering service. (Output) 
Entry: user info Souter module 

This entry point returns the name of the user's outer module. 
USAGE 

declare user_i nf o_$outer_modul e entry (char (*) ) ; 
call user_i nf o__$outer_module (om) ; 
ARGUMENTS 
om 

is the name of the user's outer module (maximum of 32 characters). (Output) The 
outer module is the initial I/O module attached to the user_i/o switch. 

Entry: user info $process type 

This entry point returns information about the type of the current process. 
USAGE 

declare user_i nf o_$process_type entry (fixed bin (17)); 
call user_i nf o_$process_type (process_type) ; 
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ARGUMENTS 
process_type 

is the type of the user's current process. (Output) It can be: 

1 interactive 

2 absentee 

3 daemon 

Entry: user info Sresponder 

The user_info_$responder entry point returns the name of the user's login responder. 
USAGE 

declare user_i nf o_$responder entry (char (*) ) ; 
call user_i nf o_$responder (resp) ; 
ARGUME NTS 
resp 

is the name of the user's login responder (maximum of 64 characters). (Output) 
Entry: user info $rs name 

This entry returns the name of the rate structure that is in effect for the process in 
which the call is made. 

USAGE 

del user_i nf o_$rs_name entry (char (*) ) ; 
call user_i nf o_$rs_name (rs_name) ; 
ARGUMENTS 
rs_name 

is the name of the rate structure in effect for this process. (Output) (The name 
may be up to 32 characters long). 
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Entry: user info $rs number 

This entry returns the number of the rate structure that is in effect for the process 
in which the call is made. 

USAGE 

del user_i nf o_$rs_number entry (fixed bin (9)); 
call user_i nf o_$rs_number (rs_number) ; 
ARGUMENTS 
rs_number 

is the number of the rate structure in effect for this process. (Output) 



Entry: user info Sservice type 

This entry point returns the service type of the terminal on which the user logged in. 
USAGE 

declare user_i nf o_$service_type entry (fixed bin); 
call user_i nf o_$servi ce_type (type); 
ARGUMENTS 
type 

is a number representing the service type of the user's terminal. (Output) It can 
be: 

1 login type; interactive command level. 

2 FTP type; Advanced Research Projects Agency Network (ARPANET) file 

transfer protocol 



Entry: user info Sterminal data 

This entry point returns information about the terminal on which the user is logged 
in. 

USAGE 

declare user_i nf o_$ termi na l_data entry (char (*) , char (*) , char (*) , 
fixed bin, char (*) ) ; 

call user_i nfo_$termi nal_data (id_code, type, channel, line_type, 
charge_type) ; 
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ARGUMENTS 
id_code 

is the identifier code of the user's terminal (maximum of 4 characters). (Output) 

type 

is the type of terminal as it was at login time. (Output) 
channel 

is the channel identification (maximum of 32 characters). (Output) 
line_type 

is the line type associated with the channel. (Output) 
charge_type 

is the name of the device charge associated with the user's login terminal 
(maximum of 8 characters). (Output) The rate can be found in the array returned 
by system_info_$device_prices. 



Entry: user info Susage data 

This entry point returns user usage data. 
USAGE 

declare user_i nf o_$usage_data entry (fixed bin, fixed b i n (7 1 ) • 

fixed bi n (71) , fixed bin(7U, fixed bin(7D, fixed bin(7D); 

call user_i nf o_$usage_data (nproc, old_cpu, time_login, time_create, 
o 1 d_mem , o 1 d_i o_ops) ; 

ARGUMENTS 

nproc 

is the number of processes created for this login session. (Output) 
old_cpu 

is the CPU time used by previous processes in the login session. (Output) 
time_login 

is the time the user logged in. (Output) It is expressed as a calendar clock 
reading in microseconds. 

time_create 

is the time that the current process was created. (Output) 
old_mem 

is the memory usage by previous processes in this login session. (Output) 
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old_io_ops 

is the number of terminal I/O operations by previous processes in this login 
session. (Output) 



Entry: user_info Swhoami 

The user_info_$whoami entry point is the same as the user_info_ entry point. The 
name is a mnemonic device added for convenience. 

USAGE 

declare user_i nf o_$whoami entry (char (*) , char (*) , char (*) ) ; 
call user_i nf o_$whoami (person__id, project_id, acct) ; 
ARGUMENTS 
person_id 

is the user's name from the login line .(maximum of 22 characters). (Output) 
projected 

is the user's project identifier (maximum of 9 characters). (Output) 

acct 

is the user's account identifier (maximum of 32 characters). (Output) 



Name: valid decimal 

The valid_decimal_ subroutine tests decimal data for validity. 
USAGE 

declare val id_decimal_ entry (fixed bin, ptr, fixed bin) returns 
(bit(l)); 

b = val id_decimal_ (dtype, dptr, dprec) ; 

ARGUMENTS 
dtype 

is the data type descriptor of the decimal data. It must be one of the following: 
9-12, 29, 30, 35-36, 38-39, 41-46 81-84. (Input) 

dptr 

is a pointer to the data to be tested for validity. (Input) 
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dprcc 

is the precision of the data. (Input) 

b 

is the value returned by valid_decimal_. It is "l"b if the data is valid, "0"b 
otherwise. (Output) 

NOTES 

For decimal data to be valid, it must pass the following tests: 

(1) The precision must be > 0 and <= 59; 

(2) The data type descriptor must be one handled by valid_decimal_; 

(3) If the data is stored as nonoverpunched 9-bit characters, then if it has a sign, 

then the sign must be either "+" or The digits must all be one of the 
ASCII characters "0123456789"; 

(4) If the data is stored as overpunched 9-bit characters, ihen the sign character must 

be either octal 173, 175, or in the range 101 to 122. The remaining digits must 
all be one of the ASCII characters "0123456789"; 

(5) If the data is stored as 4-bit characters, then if it has a sign, then sign must be 

in the range "1010"b to "llll"b. All digits must be in the range "0000"b to 
"100l"b. 



Name: value 

The value_ subroutine reads and maintains value segments containing name-value pairs 
across process boundaries. 

To initialize a new value segment, create a segment with suffix "value" and call 
value_$init_seg with a pointer to its base. The default value segment is initially: 

[home_di r]>[user_name] .value 

but can be changed by value_$set_path or the value_set_path (vsp) command. 

Perprocess values are stored in a temporary value segment in the process directory, 
and disappear when the process terminates. 
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Entry: value Sdefined 

This entry point returns "l"b if a value is defined for name, "0"b otherwise. 
USAGE 

declare val ue_$def i ned entry (ptr, bit (36), char (*) , fixed bin (35)) 
returns (bit (1) ) ; 

defined_sw = val ue_$def i ned (seg_ptr, switches, name, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the base of a value segment. (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, looks for a perprocess value, as opposed to one 
stored in the value segment Either this switch or "permanent" must be on. 
If both switches are on, a perprocess value is returned if one exists, 
otherwise a value stored in the value segment is returned, 
permanent 

If bit number two is ON, looks for a value stored in the value segment. 

name 

is a character string with at least one nonblank character. (Input) Trailing blanks 
are trimmed. 

code 

is a standard status code. (Output) 
NOTES 

The user requires r access on the value segment, except for perprocess values. 



Entry: value $delete 

This entry point causes there to be no value defined for name. 
USAGE 

declare val ue_$del ete entry (ptr, bit(36), char (*) , fixed bin (35)); 
call val ue_$del ete (seg_ptr, switches, name, code); 
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ARGUMENTS 
seg_ptr 

is a pointer to the base of a value segment. (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, deletes a perprocess value, as opposed to one 
stored in the value segment Either this switch or "permanent" must be on. 
If both switches are on, the perprocess value is deleted if one exists, 
otherwise the value in the value segment is deleted, 
permanent 

If bit number two is ON, deletes a value stored in the value segment. 

name 

is a character string with at least one nonblank character. (Input) Trailing blanks 
are trimmed. 

code 

is a standard status code. (Output) 
NOTES 

The user requires rw access on the value segment, except for perprocess values. 



Entry: value Sdelete data 

This entry point deletes values set by value_$set_data. 
USAGE 

declare val ue_$del ete_data entry (ptr, bit (36), char (*) , fixed bin(35))» 
call va 1 ue_$del ete_data (seg_ptr, switches, name, code); 
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ARGUMENTS 
seg_ptr 

is a pointer to the base of a value segment If seg^ptr is null, the default value 
segment is used. (Input) 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, deletes a perprocess value, as opposed to one 
stored in the value segment. Either this switch or "permanent" must be on. 
If both . switches are on, the perprocess value is deleted if one exists, 
otherwise a value stored in the value segment is deleted, 
permanent 

If bit number two is ON, deletes a value stored in the value segment. 

name 

is a character string with at least one nonblank character. Trailing blanks are 
trimmed. (Input) 

code 

is a standard status code. (Output) 
NOTES 

The user requires rw access on the value segment, except for perprocess values. 



Entry: value $get 

This entry point returns the defined value of a name. 
USAGE 

declare value_$get entry options (variable); 

call value_$get (seg_ptr, switches, name, value_arg, code); 
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seg_ptr 

is a pointer to the base of a value segment. (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, looks for a perprocess value, as opposed to one 
stored in the value segment. Either this switch or "permanent" must be on. 
If both switches are on, a perprocess value is returned if one exists, 
otherwise a value stored in the value segment is returned, 
permanent 

If bit number two is ON, looks for a value stored in the value segment. 

name 

is a fixed-length or varying character string. (Input) If fixed-length, trailing 
blanks are trimmed. There must be at least one character. 

value_arg 

is the returned value, having any data type. (Output) If conversion from the 
internal character string representation cannot be performed, 
error_table_$bad_conversion is returned. Conversion errors cannot occur if value_arg 
is a character string, but if it has a maximum length greater than 0 and 
truncation occurs, the error code error_table_$smallarg is returned. 

code 

is a standard error code. (Output) It is error_table_$oldnamerr ("Name not 
found.") if no value is defined. 

NOTES 

The user requires r access to the value segment, except for perprocess values. 



Entry: value $get data 

This entry point returns, into a caller-supplied buffer, the region of storage that is 
defined as the value of a name, as set by either value_$set_data or value_$test_and_set_data. 
Values set by other entry points are not seen by value_$get_data. 

USAGE 

declare va 1 ue_$get_data entry (ptr , bit(36), char (*) , ptr, ptr, 
fixed bin (18) , fixed bin (35) ) ; 

call value_$get_data (seg_ptr, switches, name, area_ptr, data_ptr, 
data size, code) ; 
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ARGUMENTS 
seg_ptr 

is a pointer to the base of a value segment. (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, looks for a perprocess value, as opposed to one 
stored in the value segment Either this switch or "permanent" must be on. 
If both switches are on, a perprocess value is returned if one exists, 
otherwise a value stored in the value segment is returned, 
permanent 

If bit number two is ON, looks for a value stored in the value segment. 

name 

is a character string with at least one nonblank character. (Input) Trailing blanks 
are trimmed. 

area_ptr 

points to an area in which the value can be allocated. (Input) 
data_ptr 

points to the value returned. (Output) 
data_size 

is the number of words in the value. (Output) 

code 

is a standard error code. (Output) It is error_table_$oldnamerr ("Name not 
found.") if no value is defined. 

NOTES 

The user requires r access on the value segment, except for perprocess values. 



Entry: value $get path 

This entry point returns the pathname of the current default value segment used by 
value commands without -pathname. 

USAGE 

declare va 1 ue_$get_path entry (char (*) , fixed bin (35)); 
call val ue_$get_path (path, code); 
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ARGUMENTS 
path 

is the pathname. (Output) 

code 

is a standard status code. (Output) 
Entry: value Sinit seg 

This entry point initializes a segment to be a value segment. 
USAGE 

declare val ue_$ i n i t_seg entry (ptr, fixed bin, ptr, fixed bin(19)» 
f i xed bin (35) ) ; 

call value_$ini t_seg (seg_ptr, seg_type , remote_area_ptr , seg_s i ze. 
code) ; 

ARGUMENTS 

seg_ptr 

is a pointer to a segment (Input) 
seg_type 

determines the type of use to which the value segment will be put, and therefore 
the method of allocating values: (Input) 

0 permanent: shareable by multiple processes and therefore locked when modified, 

with values always stored in the value segment itself. 

1 perprocess: for use only by the calling process and therefore never locked, 

with values optionally stored in an area outside the value segment (see the 
remote_area_ptr argument below). 



remote_area_ptr 

for a perprocess segment only, points to an area outside the value segment in 
which values are to be allocated. (Input) For example, the value segment can be 
a region of storage 72 words long consisting only of a header, and remote_area_ptr 
can point to the user's own area. If remote_area_ptr is null and seg_type is 1, 
values are allocated in the system free area. 
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seg_size 

is the number of words available to the value segment, or to the remote area if 
remote_area_ptr is nonnull. (Input) If seg_size is 0, the available size is an entire 
segment. 

code 

is a standard status code. (Output) 
NOTES 

The user requires rw access on the value segment. 



Entry: value Slist 

This entry point returns a list of variable names and their values when given a list of 
starnames and regular expressions to match and exclude. Only values set by value_$set 
are returned; see value_$list_data_names to list variables set by value_$set_data. 

USAGE 

declare value_$1ist entry (ptr, bit(3&) aligned, ptr, ptr, ptr, 
fixed bin (35)) > 

call value_$list (seg_ptr, switches, match_i nf o_ptr , area_ptr, 
va 1 ue_l i st_i nf o_ptr , code); 

ARGUMENTS 
seg_ptr 

is a pointer to the base of a value segment. (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, looks for perprocess values, as opposed to those 
stored in the value segment. Either this switch or "permanent" must be on. 
If both switches are on, both kinds of values are listed, 
permanent 

If bit number two is ON, looks for values stored in the value segment. 
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match_inf o_ptr 

is a pointer to the following user-allocated structure, declared in 
value_structures. incl. pll: (Input) 

del 1 match_info aligned based (match_i nf o_ptr) , 
2 version fixed bin, /* = 1 */ 

2 name_count fixed bin, 
2 max_name_l en fixed bin (21), 
2 name_array (al 1 oc_name_count refer 

(match_i nf o. name_count) ) , 
3 exclude_sw bit (1) unaligned, 
3 regexp_sw bit (1) unaligned, 
3 pad bit (34) unaligned /* = "0"b */ 

3 name char (al loc_max_name_len refer 

(match_i nf o.max_name_l en) ) varying; 

If a name's regexp_sw is ON, the name is a regular expression to be matched. 
Otherwise, it is a starname to be matched. If the name's exclude_sw is ON, 
variables matching the name are excluded from the list built up so far, as for the 
-exclude control argumeni to the value_list command. Otherwise, matching 
variables are added to the list. (See "Examples" below.) 

area_ptr 

is a pointer to an area in which the output value_list_info structure is to be 
allocated. (Input) 

value_list_inf o_ptr 

is a pointer to the following structure, allocated by value_$list and fTeed by the 
caller when done. (Output) It is also declared in the include file 
value_structures.incl.pll: 

del 1 val ue_l i st_i nf o aligned based (val ue_l i st_i nf o_ptr) , 
2 version fixed bin, /» - 1 */ 

2 pair count fixed b i n ; 

2 chars_len fixed bin (21), 

2 pairs (a 1 1 oc_pai r_count refer 

(value_l i st_info.pai r_count) ) , 
3 type_swi tches bit (36), 
3 name_ index fixed bin (21), 
3 name_len fixed bin (21), 

3 value_index fixed bin (21), 
3 value_len fixed bin (21), 
2 chars char (al loc_chars_l en refer 

(value list info. chars len)); 
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For each pair (i), the variable name is: 



substr (chars, name_index (i) , name_len (i)) 



and the value is: 



substr (chars, val ue_i ndex (i) , value_len (i)) 



code 



is a standard status code. (Output) 



NOTES 



The user requires r access on the value segment, except for perprocess values. 
Names are returned in alphabetical order. 

The user is responsible for freeing the value_list_info structure when done. 
EXAMPLES 

In the match_info structure, names are matched in the order given. Those with 
exclude_sw OFF add to the list (union) and those with exclude_sw ON narrow down 
the list (intersection). For example, assume the defined variables to be rs_seg_length, 
rs_area_length, rs_str_ptr, rs_str_len, arg_str_ptr, and arg_str_len, and assume the 
following entries in match_info: 



The first name causes the list of selected variables to be: 

rs_seg_l ength, rs_area_l ength, rs_str_len, arg_str_len 

The next name (with exclude_sw ON) produces the intersection of this set with the set 
of names NOT matching /_ length/: 

rs_strjen, arg_str_len 

The last name produces the union of this set with the set of names matching 
/seg_l ength/: 

rs_str_len, arg_str_len, rs_seg_l ength 

which is the set of names returned in value_info. 



(exc 1 ude_sw) 



(name) 
/Jen/ 
/J ength/ 
/segjength/ 



OFF 

ON 

OFF 
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Entry: value $Iist__data names 

This entry point operates exactly the same as value_$list, but returns variables set by 
value_$set_data instead of value_$set, and does not return the values. Instead, it sets 
value_list_info.value_len to the number of words in the value. 

USAGE 

declare val ue_$ 1 i st_data_names entry (ptr, bit (36) aligned, ptr, ptr, 
ptr , fixed bin (35) ) ; 

call value_$ 1 i st_data_names (seg_ptr, switches, match_i nf o_ptr , 
area_ptr, va 1 ue_l i st_i nf o_ptr , code); 

ARGUMENTS 

seg_ptr 

is a pointer to the base of a value segment (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, looks for perprocess values, as opposed to those 
stored in the value segment. Either this switch or "permanent" must be on. 
If both switches are on, both kinds of values are listed, 
permanent 

If bit number two is ON, looks for values stored in the value segment. 
match_info_ptr 

is a pointer to the user-allocated match_info structure (declared in 
value_structures.incl.pll, described under the value_$list entry point above. (Input) 

If a name's regexp_sw is ON, the name is a regular expression to be matched. 
Otherwise, it is a starname to be matched. If the name's exclude_sw is ON, 
variables matching the name are excluded from the list built up so far, as for the 
-exclude control argument to the value_list command. Otherwise, matching 
variables are added to the list (See "Examples" below.) 

area_ptr 

is a pointer to an area in which the output value_list_info structure is to be 
allocated. (Input) 

value_list_inf o_ptr 

is a pointer to the value_list_info structure (described under the value_$list entry 
point above), allocated by value_$list_data_names and freed by the caller when 
done. (Output) It is also declared in the include file value_structures.incl.pll. 
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For each pair (i), the variable name is: 

substr (chars, name_index (i) , name_len (i)) 

The first bit in type_switches (i) is ON if the variable is perprocess, the second 
is ON instead for a variable stored in the value segment. 

code 

is a standard status code. (Output) 



Entry: value $set 

This entry point defines a value for a name, readable by value_$geL 
USAGE 

declare value_$set entry options (variable); 

call value_$set (seg_ptr, switches, name, new_value, old_value, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the base of a value segment (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, sets a perprocess value, as opposed to one stored 
in the value segment. Either this switch or "permanent" must be on. If both 
switches are on, a perprocess value is set if one already exists, otherwise a 
value is set in the value segment, 
permanent 

If bit number two is ON, sets a value in the value segment. 

name 

is a fixed-length or varying character string. (Input) If fixed-length, trailing 
blanks are trimmed. There must be at least one character. 

new_value 

is the value to be set, having any data type. (Input) If conversion to the internal 

character string representation cannot be performed, error_table_$badcall is 
returned. 



2-939 



AG93-05 



value_ 



value 



old.value 

is the current value, having any data type. (Output) If no value is currently 
defined, the value of this argument is not changed. If conversion from the 
internal character string representation cannot be performed, 
error_table_$bad_conversion is returned. 

code 

is a standard error code. (Output) Having no previous value defined does not 
cause an error code to be returned. 

NOTES 

The user requires rw access to the value segment, except for perprocess values. 



Entry: value $set data 

This entry point defines the value for a name to be a specified number of words of 
data, readable by value_$get_data. Values set by this entry point cannot be seen by 
value_$get or value_$defined. 

USAGE 

declare val ue_$set_data entry (ptr, bit (36), char (*) , ptr, 

fixed bin(l8), ptr, ptr, fixed bin(l8), fixed bin(35))» 

call va 1 ue_$set_data (seg_ptr, switches, name, new_data_ptr , 

new_data_s i ze, area_ptr, old_data_ptr , ol d_data_s i ze, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the base of a value segment. (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, sets a perprocess value, as opposed to one stored 
in the value segment. Either this switch or "permanent" must be on. If both 
switches are on, a perprocess value is set if one already exists, otherwise a 
value is set in the value segment, 
permanent 

If bit number two is ON, sets a value in the value segment 

name 

is a character string with at least one nonblank character. (Input) Trailing blanks 
are trimmed. 
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new_data_ptr 

is a pointer to the value to be set (Input) 

new_data_size 

is the number of words in the value to be set. (Input) 
area_ptr 

if nonnull, points to an area in which the old (return) value is to be allocated. 
(Input) If null, the old value is not returned. 

old_data_ptr 

is a pointer to the old value. (Output) 

old_data_size 

is the number of words returned as the old value. (Output) 

code 

is a standard status code. (Output) Having no previous value defined does not 
cause an error code to be returned. 

NOTES 

The user requires rw access on the value segment, except for perprocess values. 



Entry: value $set path 

This entry point sets the default value segment used by the value commands with no 
-pathname argument. 

USAGE 

declare va 1 ue_$set_path entry (char (*) , bit(1), fixed bin (35)) ; 
call value_$set_path entry (path, create_sw, code); 
ARGUMENTS 
path 

is the pathname. (Input) The value suffix is assumed. 
create_sw 

is ON to create a value segment if none exists. (Input) 

code 

is a standard status code. (Output) If it is error_table_$no_w_permission, the 
value segment has been set. Any other nonzero code indicates that the value 
segment was not set 
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Entry: value Stest and set 

This entry point defines a new value for a name, only if the name has a specified 
current value. 

USAGE 

declare va 1 ue_$ test_and_set entry options (variable); 

call value_$test_and_set (seg_ptr, switches, name, new_value, old_value, 
code) ; 

ARGUMENTS 

seg_ptr 

is a pointer to the base of a value segment. (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, tests and sets a perprocess value, as opposed to 
one in the value segment. Either this switch or "permanent" must be on. If 
both switches are on, the perprocess value is tested if one is defined, 
otherwise the one in the value segment is tested. The value set is of the 
same type as the value tested, 
permanent 

If bit number two is ON, tests and sets the value in the value segment 

name 

is a fixed-length or varying character string. (Input) If fixed-length, trailing 
blanks are trimmed. There must be at least one character. 

new_value 

is the value to be set, having any data type. (Input) If conversion to the internal 
character string representation cannot be performed, the error code 
error_table_$badcall is returned. 

old_value 

is the caller-supplied value that must equal the value currently defined in order 
for the new value to be set. (Input) 

code 

is a standard status code. (Output) It is error_table_$action_not_performed if 
old_value does not match the currently defined value. 
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NOTES 

The user requires rw access on the value segment, except for perprocess values. 
If the value tested is perprocess, the value set is also perprocess, and vice-versa. 



Entry: value $test and set data 

This entry point defines the value for a name to be a specified number of words of 
data, readable by value_$get_data, only if the first N words of the name's current 
value have specified contents. 

USAGE 

declare val ue_$ test_and_set_data entry (ptr, bit (36), char (*) , ptr, 
fixed bin (18), ptr, fixed bin(lfi), fixed bin (35)); 

call value_$test_and__set_data (seg_ptr, switches, name, new_data_ptr , 
new_data_size, old_data_ptr , ol d_data_s i ze, code); 

ARGUMENTS 
seg_ptr 

is a pointer to the base of a value segment. (Input) If seg_ptr is null, the 
default value segment is used. 

switches 

is a bit (36) aligned word of switches: (Input) 
perprocess 

If bit number one is ON, tests and sets a perprocess value, as opposed to 
one in the value segment Either this switch or "permanent" must be on. If 
both switches are on, the perprocess value is tested if one is defined, 
otherwise the one in the value segment is tested. The value set is of the 
same type as the value tested, 
permanent 

If bit number two is ON, tests and sets the value in the value segment. 

name 

is a character string with at least one nonblank character. (Input) Trailing blanks 
are trimmed. 

new_data_ptr 

is a pointer to the value to be set (Input) If null, the current value is deleted 
and no value is defined. 

new_data_size 

is the number of words in the value to be set (Input) 
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old_data_ptr 

is a pointer to some data, whose first old_data_size words must equal the first 
old_data_size words of the name's current value in order for the new value to be 
set (Input) 

old_data_size 

is the number of words to be compared. (Input) This number can be less than 
the number of words in the name's current value (used, for example, to compare 
only the header of a structure), but an error code is returned if it is greater. 

code 

is a standard status code. (Output) It is error_table_$action_not_performed if the 
old-value match fails. 

NOTES 

The user requires rw access on the value segment, except for perprocess values. 
If the value tested is perprocess, the value set is also perprocess, and vice-versa. 
The value of a name can be conditionally deleted by passing a null new_data_ptr. 



Name: vfile status 

The vfile_status_ subroutine returns various items of information about a file 
supported by the vfile_ I/O module. 

USAGE 

declare vf i 1 e_status_ entry (char (*) , char (*) , ptr, fixed bin (35)); 
call vf i 1 e_status_ (dir_name, entryname, info_ptr, code); 
ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the file of interest. (Input) If the entry is a link, the 
information returned pertains to the entry to which it points. 

info_ptr 

is a pointer to the structure in which information is to be returned. (Input) See 
"File Information" below. 
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code 

is a storage system status code. (Output) 
FILE INFORMATION 

The info_ptr argument points to one of the following structures which are all declared 
in the include file vfs_info.incl.pll. 



Unstructured Files 

For unstructured files, use. the following structure: 

del 1 uns_info based (addr (info)), 

2 info_version fixed bin, 

2 type fixed bin, 

2 bytes fixed bin (3*0, 

2 f 1 ags al i gned, 

3 padl bi t (2) unal , 

3 header_present bit(l) unal, 

3 pad2 bit (33) unal , 

2 header_id fixed bin (35); 

where: 
info_version 

identifies the version of the info structure; this must be set to the named 
constant vfs_version_l. 

type 

identifies the file type and the info structure returned: 

1 unstructured 3 blocked 

2 sequential 4 indexed 

bytes 

gives the length of the file, not including the header in bytes. 

header_present 

if set, indicates that an optional header is present. 

header_id 

contains the identification from the header of the file, if present Its meaning is 
defined by the user. 
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Sequent i 'ai Files 



For sequential files, use the following structure: 



del 1 seq_info 



2 i nf o_vers i on 

2 type 

2 records 

2 flags 



3 pad 
2 version 



3 lock_status 



based (addr (i nf o) ) , 

fixed bin, 

f i xed bin, 

f i xed b i n (3*0 , 

al igned, 

b i t (2) unal , 

bit(3M unal, 

fixed bin; 



where: 
info_version 

identifies the version of the info structure; this must be set to the named 
constant vfs_version_l. 

type 

identifies the file type and the info structure returned: 

1 unstructured 3 blocked 

2 sequential 4 indexed 

records 

is the number of records in the file, including those of zero length. 
lock_status 

if zero, indicates that the lock of the file is not set; otherwise the file is busy. 

"OT'b busy in caller's process 

"10"b busy in another process 

"ll"b busy in a defunct process 

version 

identifies the version number of the file and its creating program. 
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Blocked Files 



For blocked files, use the following structure: 



del 1 blk info 



2 i nf o_yers i on 
2 type 
2 records 
2 flags 



3 pad 
2 version 
2 action 
2 max rec len 



3 lock_status 



based (addr (i nf o) ) , 

fixed bin, 

f i xed bin, 

f i xed bin (3*0 , 

al i gned, 

bit (2) unal, 

bit (34) unal, 

fixed bin, 

fixed bin, 

f i xed b i n (21) ; 



where: 
info_version 

identifies the version of the info structure; this must be set to the named 
constant vfs_version^l. 

type 

identifies the file type and the info structure returned: 

1 unstructured 3 blocked 

2 sequential 4 indexed 

records 

is the number of records in the file, including those of zero length. 
lock_status 

if zero, indicates that the lock of the file is not set; otherwise the file is busy. 

"01"b busy in caller's process 

"10"b busy in another process 

"IT'b busy in a defunct process 

version 

identifies the version number of the file and its creating program. 



if nonzero, indicates an operation in progress on the file: 
-1 write in progress 
-2 rewrite in progress 
-3 delete in progress 
+1 truncation in progress 

max_rec_len 

is the maximum record length (in bytes) associated with the file. 



action 
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Indexed Files 

For indexed files, use the following structure: 



1 indx info 


based 


(addr ( 


1 nfo) ) , 


2 


i nf o_vers i on 


f i xed 


bin, 




2 


type 


f i xed 


bin, 




2 


records 


fixed bin (3*0 


» 


2 


f 1 ags 


al i gned, 






3 lock_status 


bit (2) 


unal , 






3 pad 


bit (3*0 unal, 




2 


vers i on 


al i gned , 






3 f i 1 e_vers i on 


f i xed 


bin (17) 


unal , 




3 programmers i on 


f i xed 


bin (17) 


unal , 


2 


act ion 


fixed 


bin, 




2 


non_nul l_recs 


f i xed 


bin(3*0 


> 


2 


record_by tes 


fixed 


bin(3*0 


» 


2 


f ree_blocks 


f i xed 


bin, 




2 


i ndex_hei ght 


f i xed 


bin, 




2 


nodes 


r : ,. 

1 1 AtU 


u : ~ 
»_> i 1 1 , 




2 


key_bytes 


f i xed 


bin(3*0 


» 


2 


change_count 


fixed 


bin (35) 




2 


num_keys 


f i xed 


bin (310 




2 


dup_keys 


fixed 


bin (3*0 


» 


2 


dup_key__bytes 


fixed 


bin (3*0 




2 


reserved (1) 


f i xed 


bi n; 





where: 
info_version 

identifies the version of the info structure; this must be set to the named 
constant vfs_version_l. 

type 

identifies the file type and the info structure returned: 

1 unstructured 3 blocked 

2 sequential 4 indexed 

records 

is the number of records in the file, including those of zero length. 
lock_status 

if zero, indicates that the lock of the file is not set; otherwise the file is busy. 

"01"b busy in caller's process 

"10"b busy in another process 

"ll"b busy in a defunct process 

file_version 

identifies the version number of the file. 
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program_version 

identifies the version number of vfile_ that created the file. 

action 

if nonzero, indicates an operation in progress on the file: 
-1 write in progress 
-2 rewrite in progress 
-3 delete in progress 
+1 truncation in progress 

non_null_recs 

is a count, not including those of zero length, of the records in the file. 
record_bytes 

is the total length of all records in the file in bytes. 
free_blocks 

is the number of blocks in the free space of the file list for records. 
index_height 

is the height of the index tree (equal to zero if file is empty), 
nodes 

is the number of single page nodes in the index. 
key_bytes 

is the total length of all keys in the file in bytes. 
change_count 

is the number of times the file has been modified. 
num_keys 

is the total number of index entries, each associating a key with a record, 
dupjceys 

is the number of index entries with nonunique keys, not including the first 
instance of each key. 

dup_key_bytes 

is the total length of all duplicate keys in the file, as defined above. 
NOTES 

The user must provide the storage space required by the above structures. The 
following declaration: 

del info aligned like indx_info; 
will provide the necessary space for the largest of the structures. 
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See the description of the vfile_ I/O module for farther details. 



Name: video data 

The video_data_ subroutine is a data segment containing information about the video 
system. 

Entry: video data {terminal iocb 

This is the terminal control switch IOCB pointer. If the video system is activated for 
the user's terminal, this pointer is nonnull, and points to the IOCB for the switch 
user_terminal_. 

USAGE 

fnt typ declare video_data_$terminal_iocb pointer external static; 
NOTES 

User programs may use this pointer for two purposes: 

1. Inquiring as to whether the video system is activated, by checking to see if the 
pointer is null. 

2. Determining the physical characteristics and capabilities of the terminal. This may 
be accomplished with the get_capabilities control order, described under the 
window_io_ I/O module. The height and width returned will be that of the 
physical terminal screen. 

No other manipulations of this swiich are permitted. 



Name: video utils 

This subroutine provides interfaces for activating and de-activating the video system. 
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Entry: video_utiIs_$turn_on_iogin_channeI 

This entry removes the existing attachment of the user's terminal, replacing it with the 
video system. When this entry returns successfully, the switch user_terminal_ is 
attached through tc_io_ to the user's terminal. The switch user_ i/o is attached 
through window_io_ to a window covering the entire screen, invoked: vertsp, can, 
erkl, esc, red, and ctl_char. In addition, if A pl is set on video system invocation, 
A more will be set in the video system. (For more details on modes, see the 
window_io_ I/O module.) Similarly, the settings of the current erase and kill 
characters are copied when the video system is invoked. (See "Real-Time Editing" for 
details.) To see how the standard I/O switch attachments change when you activate 
the video system on your terminal, refer to Figure A-2 in Appendix A. 

USAGE 

declare video_uti 1 s_$turn_on_log i n_channel entry (fixed bin (35) » 
char (*)); 

call video_uti 1 s_$turn__on_l og i n_channel (code, reason); 

ARGUMENTS 

code 

is a standard system error code. (Output) 
reason 

contains information about the error, if there is one. (Output) (128 characters are 
enough to hold any message that may be returned in reason.) 

NOTES 

If the video system is already in service on the user's terminal, the status code 
video_et_$wsys_invoked is returned, and the value of reason is not defined. 

If the activation of the video system fails, the original attachment of the terminal 
(through tty_) is restored, and information is returned in reason and code. 

In particular, if the switch user_i/o is not currently attached through tty_, the code 
video_et_$switch_not_attached_with_tty_ is returned. This may indicate that the user 
has auditing or the graphic system in place. The message returned in reason advises 
the user to remove graphics or auditing and try again. 
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Entry: video utils Sturn off login channel 

This entry reverses the actions of video_utils_$turn_on_login_channel. That is, it 
removes the window attachment of user_i/o, detaches terminal control from the user's 
terminal, and attaches user_i/o to the user's terminal via tty_. The settings of the 
following modes are copied when when the video system is revoked: vertsp, can, erkl, 
esc, red, and ctl_char. If A more is set while in the video system, A pl mode will be 
set after revoking the video system. (For more details on modes, see the window_io_ 
I/O module.) Similarly, the settings of the current erase and kill characters are copied 
when the video system is revoked. (See "Real-Time Editing" for details.) It is the 
user's responsibility to detach any windows other than user_io before calling this entry 
point 

USAGE 

declare video_uti ls_$turn_of f_login_channel entry (fixed bin (35)); 

call video_ut i 1 s_$turn_of f_logi n_channel (code); 

ARGUMENTS 

code 

is a standard system error code. (Output) It is nonzero if and only if the video 
system can not be removed from the user's terminal. 



Name: virtual cpu__time 

The virtual_cpu_time_ function returns the CPU time used by the calling process since 
its creation; this value does not include the time spent handling page faults or system 
interrupts. It is therefore a measure of the CPU time within a process that is 
independent of other processes, current configuration, and overhead necessary to 
implement the virtual memory for the calling process. 

USAGE 

declare vi rtual_cpu_t ime_ entry returns (fixed bin(7D); 

time - vi rtual_cpu_t ime_ (); 

ARGUMENTS 

time 

is the virtual CPU time, in microseconds, used by the calling process. (Output) 
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NOTES 

The vclock builtin function should be used in PL/ 1 programs instead of this 
subroutine, because it is more efficient 



Name: window 

The window_ subroutine provides a terminal independent interface to video terminal 
operations. More specifically, it controls and performs I/O to a window. 

The window_ subroutine is used in conjunction with the iox_ subroutine call entry 
points in the window_io_ I/O module. The window_ and video_utils_ subroutines 
together perform the same functions as the window_call command. 

The virtual terminal implemented by window_ corresponds closely to common video 
terminals. The features of the terminal are defined implicitly by the entries below. 
Not all entries can be supported on all terminals. The result of calling an unsupported 
feature is the error code video_et_$capability_lacking. Programs can determine whether 
the device in question supports a given operation by using a get_capabilities control 
order, described under the window_io_ I/O module. 

Additional terminals may be supported by defining their video attributes in the 
Terminal Type File (TTF). The TTF is "described in the Multics Programmer's 
Reference Manual, Order No. AG91. 

Some entry points require that the current cursor position be defined when they are 
called. The current position is defined unless a call is made to the write_raw_text 
entry point, or an asynchronous event changes the window contents. If the current 
position is not defined, these entry points will return the status code 
video_et_$cursor_position_undefined. 

If an asynchronous event changes the state of the window, status will be set for the 
window. Once window status is set, all calls to window_ on that window will return 
the status code video_et_$window_status_pending until a get_window_status control 
order is used to pick up the status. 

The calling sequences for all the entry points are in the include file window_dcls.incl.pll. 
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Entry: window $bell 

This entry activates the terminal alarm. For most terminals, this will be the audible 
bell. For some it will be a visible signal. 

USAGE 

declare wi ndow_$bel 1 entry (ptr, fixed bin (35)); 
call window_$bell (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be dfined for this call. If the cursor is in some 
other window on the screen when this call is made, it is moved to the current 
position in this window. 

Entry: window Schange column 

This entry moves the cursor to a different column on the current line, without 
changing the line. 

USAGE 

declare window $change column entry (ptr ; fixed bin ; fixed bin (35)) * 
call wi ndow_$change_col umn (iocb_ptr, new_column, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

new_column 

is the new column. (Input) 

code 

is a standard system error code. (Output) 
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NOTES 

The current cursor position must be defined. 
Entry: window $change line 

This entry moves the cursor to a new line without changing the column. 
USAGE 

declare wi ndow_$change_l i ne entry (ptr, fixed bin, fixed bin (35)); 

call wi ndow_$change_l i ne (iocb_ptr, new_line, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

new_line 

is the new line. (Input) 

code 

is a standard system error code. (Output) 
Entry: window $clear region 

This entry replaces the contents of the region specified with spaces, and leaves the 
cursor at the upper left-hand corner of the region. The region is defined by giving 
the upper left-hand corner (line and column), and the width and height of the region. 

USAGE 

declare wi ndow_$c 1 ear_reg i on entry (ptr, fixed bin, fixed bin, fixed 
bin, fixed bin, fixed bin (35)); 

call wi ndow_$clear_region (iocb_ptr, start_line, start_col , n_lines, 
n__col s, code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
start_line 

is the number of the line where clearing will begin. (Input) 
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start_co! 

is the number of the column where clearing will begin. (Input) 
n_lines 

is the number of lines which will be cleared. (Input) 
n_cols 

is the number of columns which will be cleared. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The rectangular region described in cleared. The cursor position defined at (start_line, 
start_col). 

Entry: window Sclear to end of line 

This entry clears everything to the right of the cursor on the current line to spaces. 
Positions to the left of the cursor are not affected. The cursor is not moved. 

USAGE 

declare wi ndow_$clear_to_end_of_l i ne entry (ptr, fixed bin (35)); 
call wi ndow_$c lear_to_end_of_l i ne (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The cursor position must be defined. 
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Entry: window Sclear to_end of window 

This entry clears all of the window between the cursor and the end of the window. 
This includes everything to the right of the cursor on the current line, and all lines 
below the cursor. The cursor is not moved. 

USAGE 

declare wi ndow_$cl ear_to_end_of_wi ndow entry (ptr, fixed bin (35)) > 
call wi ndow_$ clear _to_end_of_wi ndow (iocbjptr, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. 
Entry: window Sclear window 

This entry clears the entire window to spaces, and, leaves the cursor at home. 
USAGE 

declare window_$clear_window entry (ptr, fixed bin (35) ) » 
call wi ndow_$cl ear _wi ndow (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The cursor position is defined to be at line 1, column 1 after the screen is cleared. 
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Entry: window__$create 

This entry creates a new window on the terminal screen. 
USAGE 

declare wi ndow_$ create entry (ptr, ptr, ptr, fixed bin (35)); 

call wi ndow_$create . (termi nal_i ocb_ptr , wi ndow_i nf o_ptr , 
window_iocb_ptr, code); 

ARGUMENTS 

terminal_iocb_ptr 

is a pointer to an IOCB for the terminal control switch. (Input) Normally this 
should be video_data_$terminal_iocb. 

window_info_ptr 

is a pointer to a standard window_position_info structure, as declared in 
window_control_inf o.incl.pll. (Input) 



is a pointer to a detached IOCB pointer. (Input) It may be obtained with 
iox_$find_iocb which must be done before the call to window_$create. For 
example: 

call iox__$f i nd_iocb ("top_wi ndow", wi ndow_i ocb_ptr , code); 
where the value returned for window_iocb_ptr is used in the call to window_$create. 

code 

is a standard system error code. (Output) 
NOTES 

The window_info_ptr must point to a window_position_info structure, as declared in 
window_control_inf o.incl.pll. If window_position_info. width is set to zero, the window 
will occupy the full width of the screen. Currently windows must occupy the full 
* width of the screen. If window_position_info.height is set to zero, the remainder of 
the screen is used. The iocb_ptr is an input argument, iox_$find_iocb may be used to 
obtain an iocb_ptr for a new switch. 
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Entry: window^ Sdelete chars 

This entry deletes characters on the current line. Characters to the right of the cursor 
are moved to the left. Character positions opened up on the right margin are filled 
with spaces. It is an error to call this entry point if the terminal does not support 
the delete chars operation. 

USAGE 

declare wi ndow_$delete_chars entry (ptr, fixed bin, fixed bin (35) ) » 

call window_$delete_chars (iocb_ptr, n_chars, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
n_chars 

is the number of characters (starting at the current cursor position) that will be 
removed from the screen. (Input) If n_chars is zero, no action is taken. 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. The number of characters specified by 
n_chars are deleted, and the remaining characters on the line, if any, move leftward 
to occupy the space. 



Entry: window_ _$destroy 

This entry destroys an existing window, leaving its IOCB in a detached state. 
USAGE 

declare wi ndow_$destroy entry (ptr, fixed bin (35)) » 

call wi ndow_$destroy (window_iocb_ptr, code); 

ARGUMENTS 

window_iocb_ptr 

is a pointer to an IOCB attached with window_$create. (Input) 
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code 

is a standard system error code. (Output) 



Entry: window $edit line 

This entry allows applications to preload the video editor input buffer with a string. 
USAGE 

declare window $edit line entry (pointer, pointer, pointer, fixed bin 
(21), fixed bin (21), fixed bin (35)); 

call wi ndow_$edi t_J i ne (wi ndow_iocb__ptr , wi ndow_edi t_l i ne_i nf o_ptr , 
buffer_ptr, buffer_len, n_returned, code); 

ARGUMENTS 

window_iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io. (Input) 

*3 

VY UlUUW_CUH_HU6_lm U_JJU 

is a pointer to a window_edit_line_info structure, as declared in 
window_control_info.incl.pll (described below). (Input) 

buffer_ptr 

is a pointer to a buffer where the users input will be put. (Input) 

buffer_len 

is the size of the input buffer. (Input) 

n_returned 

is the number of characters in the final output line. (Output) 

code 

is a standard system error code. (Output) 
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NOTES 

The window_edit_line_inf o structure is declared in window_control_info_inc!.pll: 

del 1 window_edi t_l ine_info based (wi ndow_edi t_l i ne_i nfo_ptr) , 

2 version char (8) , 

2 line_ptr ptr, 

2 1ine_length fixed bin (21); 

del wi ndow_edi t_l i ne_i nf o_version_l 

char (8) static options (constant) init ("wedlOOOl") ; 

del window_edi t_J ine_info_ptr ptr; 

STRUCTURE ELEMENTS 

version 

is the version number of the structure. This is currently window_edit_line_version_l. 
(Input) 

line_ptr 

is a pointer to the initial text string to be loaded into the input buffer before 
editing begins. (Input) 

line_length 

is the length of the string pointed to by line_ptr. (Input) 
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Entry: window $get cursor position 

This entry is used to return the current position of the cursor. If the last operation 
done to the terminal was in some other window, this will not be the actual position 
of the cursor on the screen. 

USAGE 

declare window_ $get_cursor_pos i t i on entry (ptr, fixed bin, fixed bin, 
fixed bin (35)) ; 

call wi ndow_$get_cursor_pos i t i on (iocb_ptr, line, col, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

line 

is the line number. (Output) 

col 

is the column position. (Output) 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. 



Entry: window Sget echoed chars 

This entry accepts input from the typist, echoing the characters as typed, until either 
a specified number of characters are read, or a break character is encountered. By 
default, the break characters are the control characters plus DEL (177 octal). 

USAGE 

declare wi ndow_$get_echoed_chars entry (ptr, fixed bin (21), char (*) , 
fixed bin (21), char (1) varying, fixed bin (35)); 

call wi ndow_$get_echoed_chars (iocb_ptr, n_to_get, buffer, n_got, break, 
code) ; 
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ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
n_to _get 

is the number of columns (N) between the cursor and the end of the line. 
(Input) At most N characters will be returned. 

buffer 

is the caller-supplied buffer that holds characters returned. (Input) 
n_got 

is the number of characters returned. (Output) Each character is echoed, 
break 

is the character that causes the echoing to stop. (Output) This character is not 
echoed. 

code 

is a standard system error code. (Output) 
NOTES 

This entry point returns no more than n_to_get characters in buffer. It reads and 
echoes characters until either (1) it has read n_to_get characters, or (2) it has read a 
break character. If it stops due to a break character, the break character is returned 
in break, otherwise break is equal to "". 



Entry: window $get one unechoed char 

This entry reads a single character, unechoed, from the terminal. Optionally, it can 
return instead of waiting if there are no characters available. 

USAGE 

declare wi ndow_$get_one_unechoed_char entry (ptr, char (1) varying, 
bit (1) aligned, fixed bin (35)); 

call wi ndow_$get_one_unechoed_char (iocb_ptr, char_read, block_flag, 
code) ; 
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ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
char_read 

is the read character. (Output) If block_flag is "0"b, and no input is typed 
ahead, then this will be a zero length character string. 

block_flag 

if this flag is "l"b, input from the terminal is awaited if none is available. 
(Input) If it is "0"b, and no input is available, then this entry returns 
immediately, and sets char_read to "". 

code 

is a standard system error code. (Output) 
NOTES 

Beware of the PL/I language definition of character string comparisons when using 
this entry with a block flag of "0"b. In PL/I, both of the following comparisons are 
true: 

(" " = " ") 
^iiii _ ii 

That is, a zero length varying string compares equally to a single space. To test if 
char_read is nonempty, use an expression like: 

(length (char_read) > 0) 



Entry: window $get unechoed chars 

This entry accepts input from the typist, leaving it unechoed, until either a specified 
number of characters are read, or a break character is encountered. 

USAGE 

declare wi ndow_$get__unechoed_chars entry (ptr, fixed bin (21), char (*) , 
fixed bin (21), char (1) varying, fixed bin (35)); 

call wi ndow_$get_unechoed_chars (iocb_ptr, n_to_get, buffer, n_got, 
break, code) ; 
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ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
n_to_get 

is the number of columns (N) between the cursor and the end of the line. 
(Input) At most N characters will be returned. 

buffer 

is the caller-supplied buffer that holds characters returned. (Input) 
n_got 

is the number of characters returned. (Output) Each character is echoed, 
break 

is the character that causes the echoing to stop. (Output) This character is not 
echoed. 

code 

is a standard system error code. (Output) 
NOTES 

This entry point will read no more than n_to_get characters from the terminal, 
without echoing them to the typist. The characters are returned in the buffer. 
Characters are read until either (1) n_to _get characters are read, or (2) a break 
character is read. If reading stops due to a break character, then the break character 
is returned in break. Otherwise break is "" 



Entry: window Sinsert text 

This entry inserts text at the current cursor position. Text at the cursor or to the 
right of the cursor is shifted to the right, to accommodate the new text. It is an 
error to call this entry if the terminal does not support the insertion of text. 

USAGE 

declare wi ndow_$ i nsert_text entry (ptr, char (*) , fixed bin (35)); 
call wi ndow__$ i nser t_text (iocb_ptr, text, code); 
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ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

text 

is the character string to be written. (Input) When converted to output, each 
character in this string must occupy exactly one print position. The length of this 
string must be such that characters moved to the right will remain on the current 
line in the window. If these conditions are not met, the result is undefined. The 
cursor is left after the last character inserted. 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. The string "text" must contain only 
printable ASCII graphics. If it contains any other characters, the status code 
video_et_$string_not_printable is returned. 



Entry: window Soverwrite text 

This entry writes text on the window in the current cursor location. If there is any 
text at or to the right of the current cursor position in the window, it is overwritten 
with the supplied string. 

USAGE 

declare wi ndow_$overwr i te_text entry (ptr, char (*) , fixed bin (35)); 

call wi ndow_$overwr i te_text (iocb_ptr, text, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

text 

is the character string to be written. (Input) This string should consist of only 
printable ASCII graphics (octal codes 040 through 176 inclusive), and may not be 
longer than the space remaining on the current line. 

code 

is a standard system error code. (Output) 
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NOTES 

The cursor position must be defined. The string "text" may contain only printable 
ASCII graphics. If it contains anything else the status code video_et_$string_not_printable 
is returned. 



Entry: window {position cursor 

This entry moves the cursor to any requested position in the window. It defines the 
current cursor position if it is undefined. 

USAGE 

declare wi ndow_$pos i t i on_cursor entry (ptr, fixed bin, fixed bin, 
fixed bin (35)) ; 

call wi ndow_$posi tion_cursor (iocb_ptr, line, col, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) line is 
the line number. (Input) 

col 

is the column position. (Input) 

code 

is a standard system error code. (Output) 



Entry: window {position cursor rel 

The entry moves the cursor relative to the current location. 
USAGE 

declare wi ndow_$pos i tion_cursor_rel entry (ptr, fixed bin, fixed bin, 
fixed bin (35) ) 5 

call window_$posi tion_cursor_re1 (iocb_ptr, line_inc, col__inc, code); 
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ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
line_inc 

is the change in line number. (Input) If line_inc is a positive number, the cursor 
is moved down. If it is a negative number, the cursor is moved up. If it is 
zero, the cursor's line number is not changed. 

col_inc 

is the change in column position. (Input) If col_inc is a positive number, the 
cursor is moved to the right. If it is a negative number, the cursor is moved to 
the left. If it is zero, the cursor's column position is not changed. 

code 

is a standard system error code. (Output) 



Entry: window $scroll__region 

This entry scrolls a region up or down a given number of lines. A positive scroll 
count scrolls the window up, deleting lines from the top of the window and adding 
new blank lines to the bottom. The cursor's new position is at the beginning of the 
first new blank line. A negative count scrolls the window down, deleting lines from 
the bottom and adding lines to the top. The cursor is left at home. If this entry is 
called and the terminal does not support either scrolling or insert and delete lines, the 
result is an error status, video_et_$capabilities_lacking. 

USAGE 

declare wi ndow_$scrol l_regi on entry (ptr, fixed bin, fixed bin, fixed 
bin, fixed bin (35) ) 5 

call wi ndow_$scrol l_regi on (iocb_ptr, start_line, n_lines, 
scrol l_di stance, code); 

ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
start_line 

is the number of the first line of the region. (Input) 
n_lines 

is the number of lines that compose the region. (Input) 
scroll_distance 

is the distance in lines by which the region will be scrolled. (Input) 
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code 

is a standard system error code. (Output) 
NOTES 

The cursor position is defined to be column one on first_line. The region from 
first_line for n_lines is scrolled scroll_distance lines, which may be negative. 



Entry: window Ssync 

This entry synchronizes the process with the typist by writing any pending output to 
the terminal. 

USAGE 

declare window_$sync entry (ptr, fixed bin (35)); 
call wi ndow_$sync ( i ocb_ptr , code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The calling process is made to wait until the typist types something after the last text 
output has been transmitted to the terminal. 



Entry: window Swrite raw text 

This entry is used to output a terminal dependent sequence. The current cursor 
position becomes undefined after this call is made. This entry should not be used to 
output sequences that put graphics onto the terminal screen, as the video system's 
internal screen image will become inconsistent. This entry is used for terminal-specific 
features that cannot be accessed via the video system. 

USAGE 

declare wi ndow_$wr i te_raw_text entry (ptr, char (*) , fixed bin (35))? 
call wi ndow_$wr i te_raw_text (iocb_ptr, text, code); 
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ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 

text 

is any string of printable ASCII characters to be transmitted to the terminal. 
(Input) 

code 

is a standard system error code. (Output) 
NOTES 

Any call to window_$write_raw_text causes the cursor position to become undefined 
and sets the screen_invalid window status flag. Subsequent calls to write_raw_text will 
ignore this flag, but all other window_ entrypoints will return the status code 
video_et_$window_status_pending until the status flag is cleared. It is the responsibility 
of the application performing the raw output call to perform a get_window_status 
control order to clear the status flag. 



Entry: window $write sync read 

This entry writes a prompt, synchronizes input to the output of the prompt, and reads 
a response. This entry is useful for queries where it is important to avoid interpreting 
type-ahead as a response to a question. 

USAGE 

declare wi ndow_$wr i te_sync_read entry (ptr, char (*'«), fixed bin (21), 
char (*) , fixed bin (21), char (1) varying, fixed bin (35)); 

call wi ndow_$wr i te_sync_read (iocb_ptr, prompt, n_to_get, buffer, n_got, 
break, code) ; 
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ARGUMENTS 
iocb_ptr 

is a pointer to an IOCB for a switch attached with window_io_. (Input) 
prompt 

is a string of printable ASCII characters which must fit on the current line. 
(Input) 

n_to_get 

is the number of columns (N) between the cursor and the end of the line. 
(Input) At most N characters will be returned. 

buffer 

is the caller-supplied buffer that holds characters returned. (Input) 
n_got 

is the number of characters returned. (Output) Each character is echoed, 
break 

is the character that causes the echoing to stop. (Output) This character is not 
echoed. 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. This entry overwrites the text string 
"prompt" at the current cursor position. It then reads characters typed after the 
prompt has been transmitted to the terminal. The characters are read in the same 
fashion as the get_unechoed_chars entry point. Any characters read before the prompt 
is transmitted, are buffered and returned to get_echoed_chars or subsequent 
gei_unechoed_chars calls. 



Name: write allowed 

The write_allowed_ function determines whether a subject of specified authorization 
has access (with respect to the access isolation mechanism) to append (but not modify 
or destroy) data to an object of specified access class. For information on access 
class, see the Multics Programmer's Reference Manual., Order No. AG91. 

USAGE 

declare wr i te_al lowed_ entry (b i t (72) aligned, b i t (72) aligned) returns 
(bit (1) al igned) ; 
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returned_b i t = wr i te_a 1 1 owed_ (authorization, access_c i ass) ; 

ARGUMENTS 

authorization 

is the authorization of the subject (Input) 

access_class 

is the access class of the object (Input) 

returned_bit 

indicates whether the subject is allowed to write the object. (Output) 
T'b write is allowed. 
"0"b write is not allowed. 
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SECTION 3 

SYSTEM INPUT/OUTPUT MODULES 



The Multics input/output (I/O) system, described in detail in the Programmer's 
Reference Manual, makes use of various I/O modules to perform input and output 
operations. An I/O module is a system- (or user-) written program that controls a 
physical device and acts as an intermediary between the device and application 
program. The attachment may also be to something other than a peripheral device, 
e.g., a file in the storage system. 

I/O operations in Multics involve the attachment of an I/O switch to the I/O 
module. The basic tool for making attachments is the iox_ subroutine (described in 
section 2). Alternatively, attachments can be performed from command level by use of 
the io_call command. The I/O facilities of the programming languages can also be 
used to specify the attachment. 

The I/O modules contained in this section include the formats of attach descriptions, 
syntax of operations from command level, and information as needed concerning 
support for the different I/O operations. 

The I/O modules described in this section and their functions are: 



ansi_tape_io_ | 
is an mtape_ per-format module that supports I/O to and from ANSI standard | 
tapes under control of the mtape_ I/O module. j 

audit_ 

provides a mechanism for auditing and editing I/O on a switch. 

bisync_ 

performs stream I/O over a binary synchronous communications channel. 
cross_ring_ 

allows an outer ring to attach a switch to a preexisting switch in an inner ring 
to perform I/O operations. 

discard. 

is a sink for unwanted output. 

gH5_ 

performs stream I/O from/to a Honeywell Level 6 G115 data transmission 
terminal. 

hasp_host_ 

simulates record-oriented I/O to a single device of a workstation while 
communicating with a host system using the HASP communications protocol. 
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hasp_workstation_ 

performs record-oriented I/O to a single device of a remote terminal that 
supports the HASP communications protocol. 

ibm2780_ 

performs stream I/O from /to a device similar to the IBM 2780 data 
transmission terminal. 

ibm3270_ 

performs stream I/O from/ to a device similar to the IBM 3270 data 
transmission terminal. 

ibm3780_ 

performs stream I/O from/ to a device similar to the IBM 3780 data 
transmission terminal. 

j ibm_pc_io_ 

I supports I/O between a Multics process and a microcomputer that runs the 

j IBM PC-to-Host data transfer protocol. 

ibm_tape_io_ 

is an mtape_ per-format module that supports I/O to and from IBM standard 
labeled, unlabled, and DOS formatted tapes under control of the mtape_ I/O 
module. 

| mtape_ 

| supports I/O to and from magnetic tape volumes written in ANSI or IBM 

format. 

rdisk_ 

supports I/O from /to removable disk packs. 
record_stream_ 

provides a mechanism for doing record I/O on an unstructured file and stream 
I/O on a structured file. 

remote_input_ 

performs record input from a terminal I/O module that is assumed to be 
remote_printer_ 

formats and controls stream I/O to a remote I/O terminal that has the 
characteristics of a line printer. 

remote_punch_ 

formats and controls stream I/O to a remote I/O terminal that has the 
characteristics of a card punch. 

remote_teleprinter_ 

formats and controls stream I/O from/to a logical entity that has the 
characteristics of a teleprinter. 
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signal_io_ 

signals a condition whenever an iox_ I/O operation is performed. 

syn_ 

establishes one switch as a synonym for another. 
tape_ansi_ 

supports I/O from /to magnetic tape files according to standards proposed by 
the American National Standards Institute (ANSI). 

tape_ibm_ 

supports I/O from /to magnetic tape files according to standards established by 
IBM. 

tape_mult_ 

supports I/O from/to magnetic tape files in Multics standard tape format. 
tape_nstd_ 

supports I/O from /to tapes in nonstandard or unknown formats. 

tty_ 

supports I/O from /to terminals. 

vfile_ 

supports I/O from /to files in the storage system. 

xmodem_io_ | 
supports I/O between a Multics process and a microcomputer that runs the | 
XMODEM data transfer protocol. I 
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Name: ansi tape io 

The ansi_tape_io_ module is an mtape_ Per-Format module that supports I/O to and 
from ANSI standard tapes under control of the mtape_ I/O module. The mtape_ 
ANSI Per-Format module (referred to as the "ANSI PFM" in the remainder of this 
discussion) may be selected explicitly by the use of the mtape_ attach description 
control argument "-volume_type ansi", or implicitly if the volume mounted by mtape_ 
during attachment is recognized by RCP as being a standard ANSI tape. Tapes are 
processed by the ANSI PFM in accordance with ANSI specification X3.27-1978, 
referred to in the remainder of this document as "the Standard". 

OPENING 

Opening of the ANSI PFM is made by the iox_$open_file or the iox_$open entries 
(via the mtape_ open_file or open entries). The iox_$open_file entry provides for a 
character string open description, describing file processing attributes to be processed 
according to the wishes of the caller. The open description arguments accepted by the 
ANSI PFM are described below. If opening is made by the iox_$open entry, the file 
processing attributes are formed from the current default values of the ANSI PFM's 
open description arguments. The open description arguments have an initial default 
value, which are denoted in their respective descriptions below, or the default values 
may be changed by the user (see "Default Values" in the mtape_ I/O module 
description.). 

The opening modes supported by the ANSI PFM are sequential_input and sequential_output. 
If the opening mode specified is sequential_output, then the mtape_ attach description 
must have specified the -ring control argument or the mtape_ control operation 
ring_in must have preceded the opening attempt. 

OPEN DESCRIPTION 



CONTROL ARGUMENTS 
-append, -app 

specifies that the requested file is to be appended to the end of the file set as a 
new file. The requested opening mode must be sequential_output or the file 
opening will be aborted. 

-no_append, -napp 

specifies that the requested file is not to be appended to the end of the file set. 
(Default) 
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-block N, -bk N 

specifies the block size in bytes for output operations. For input operations, the 
block size is obtained from the file header label record. Permissible values are 
from 18 to 99996 bytes. (Default value is 2048 bytes) 

-buffer_offset, -bo 

specifies that each block will be recorded with an 8 character prefix. A template 
of a block including this prefix has the following format: 

del 1 tape_block aligned based, 

2 block_size fixed dec (7, 0) unaligned, 

2 block_number fixed dec (7, 0) unaligned, 

2 block_data char (tape_block.block_size - 8) unaligned; 

where: 

block_size 

is the block size in 9 bit bytes, including the 8 character prefix. 
block_number 

is the numerical sequence number of the block within the current physical 
file, starting at block number 0. 

block_data 

is the user specified data recorded in the block. The length of this field 
is governed by the user specified block length. 

The block_size and block_number field are recorded in the packed fixed decimal 
pll data type, so that they may be written in the same manner without regard to 
interface recording mode (nine bit or binary). The buffer offset prefix length is 
recorded in the ANSI HDR2 label record buffer offset field (character positions 
51 and 52). 

-no_buf f er_of f set, -nbo 

specifies that no block prefix will be recorded in each data block. (Default) 

-comment STR, -com STR 

specifies a user comment to be displayed on the user_output I/O switch after the 
file has been successfully opened. The comment text (STR) may be from 1 to 80 
characters in length. (Default is no -comment) 

-default_fixed_record N, 

specifies the record length to be used for "f" or "fb" formats in the absence of 
a -record specification. The intended purpose of this control argument is to 
supply a default value for record size without having to include a -record 
specification in the open description. If the user wishes to explicitly specify the 
record length, the -record control argument should be used. Although the 
-default_fixed_record control argument may appear in a users open description 
and be processed accordingly, this would not be considered the proper method of 
explicitly supplying the record length. (Default value is 80) 
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-default_spanned_record N, -dsr N 

specifies the record length to be used for "s" or "sb" formats, in the absence of 
a -record specification. The intended purpose of this control argument is to 
supply a default value for record size without having to include a -record 
specification in the open description. If the user wishes to explicitly specify the 
record length, the -record control argument should be used. Although the 
-default_spanned_record control argument may appear in a users open description 
and be processed accordingly, this would not be considered the proper method of 
explicitly supplying the record length. (Default value is 1044480) 

-default_variable_record N, -dvr N 

specifies the record length to be used for "d" or "db" formats, in the absence of 
a -record specification. The intended purpose of this control argument is to 
supply a default value for record size without having to include a -record 
specification in the open description. If the user wishes to explicitly specify the 
record length, the -record control argument should be used. Although the 
-default_variable_record control argument may appear in a users open description 
and be processed accordingly, this would not be considered the proper method of 
explicitly specifying the record length. (Default value is 2048) 

-display, -ds 

specifies that the entire open description, after it has been parsed and any 
necessary defaults added, is to be displayed on the user_output I/O switch. 

-no_display, -nds 

specifies that the open description will not be displayed on the user_output I/O 
switch. (Default) 

-expires date, -exp date 

specifies the expiration date of the file to be created, where date must be of a 
form acceptable to the convert_date_to_binary_ subroutine. (Default is no 
-expires) 

-extend, -ext 

specifies extension of an existing file. 

-no_extend, -next 

specifies that the requested file is not to be extended. (Default) 

-force, -fc 

specified that the expiration date of the file being overwritten is to be ignored. 
-no_force, =nfc 

specifies that the expiration date of a file being overwritten is not to be ignored. 
If the expiration date is not in the past, the user is queried for permission to 
overwrite the file. (Default) 
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-format F, -fmt F 

specifies the record format of the file to be created. Permissible values are: U, 
F, D, S, FB, DB, and SB. (They may be specified in either upper or lower case.) 
(Default value is DB) 

-generate, -gen 

specifies creating a new "generation" of an existing file by replacement. The file 
attributes recorded in the file header remains the same as the replaced file, but 
the generation number in the file header is incremented by 1. 

-no_generate, -ngen 

specifies that a new generation of an existing file will not be created. (Default)" 

-label_entry entry, -lbe entry 

specifies the entry point of a user subroutine which will be called to process the 
contents of user label records on input and generate the contents of same, for 
subsequent writing by mtape_ on output. (See "Calling sequence for user label 
processing routine" below.) (Default is no -label_entry) 

-last_file, -If 

specifies that the file to be processed is the last file of the file set. 
-not_last_file, -nlf 

specifies that the file to be processed may not be the last file of the file set. 
(Default) 

-mode STR, -md STR 

specifies the encoding mode used to record the file data. Permissible values of 
STR are ascii, ebcdic or binary. (Default value is ascii) 

-modify, -mod 

specifies modification of an existing file while retaining the file attributes as 
recorded in the original files header label records. 

— no_modify, — nmod 

specifies that modification of an existing file is not to be performed. (Default) 

-name STR, -nm STR 

specifies the file identifier of the requested file. STR can be from 1 to 17 
characters. (Default is no -name) 

-next_file, -nf 

specifies the file to be processed as the next (or first) file of the file set. This 
control argument is intended to be used when sequentially processing files. For 
output operations, if -name or -number are not specified, the values of their 
respective fields are fabricated by using the next sequential number as the file 
sequence number and forming the file name by concatenating the string "FILE" 
with the alphanumeric representation of the file number. (i.e. "FILEOOOl"). 
(Default) 
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-not_next_file, -nnf 

specifies that the requested file is not the next file. 

-number N, -nb N 

specifies the file sequence number or numerical position within the file set. 
Permissible values range from 1 to 9999. (Default is no -number) 

-record N, -rec N 

specifies the logical record length in bytes. Permissible values range from 18 to 
1044480 (sys_info$max_seg_size * 4) bytes, but the legality of the record size is 
dependent on the record format specified with the "-format" control argument 
and the block size. In general the record size must be <= the block size with 
the exception of spanned record formats (i.e. S or SB formats) where the record 
size may be the max allowable. (No default value. The default record size is 
determined by the value of the appropriate "-default_<type>_record" specification, 
where <type> can be either fixed, variable or spanned.) (Default is no -record) 

-replace STR, -rpl STR 

specifies replacement of an existing file, where STR is the file identifier to use in 
the search for the file to be replaced. (Default is no -replace) 

CLOSING 

Closing of the ANSI PFM is made by the iox_$close_file or the iox_$close entries 
(via the mtape_ close_file or close entries). The iox_$close_file entry provides for a 
character string close description, describing actions to be taken by the Per-Format 
module upon closing the I/O switch. If closing is made by the iox_$close entry, the 
close time actions are formed from the current default values of the ANSI PFMs 
close description arguments. The close description arguments have an initial default 
value, which are denoted in their respective descriptions below, or the default values 
may be changed by the user (see "Default Values" in the mtape_ I/O module 
description.). 

CLOSE DESCRIPTION 



CONTROL ARGUMENTS 

-close_position STR, -cls_pos STR 

specifies where to physically position the tape volume within the file that is being 
closed. The values of STR are case insensitive and may be selected from bof (for 
beginning of file), eof (for end of file), or leave (to leave the tape volume 
positioned where it is). (Default value is leave) 

-comment STR, -com STR 

specifies a user comment to be displayed on the user_output I/O switch, after the 
file has been successfully closed. The comment text (STR) may be from 1 to 80 
characters in length. (Default is no -comment) 
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-display, -ds 

specifies that the en tire close description, after if has been parsed and any 
necessary defaults added, is to be displayed on the user_output I/O switch. 

-no_display, -nds 

specifies that the close description will not be displayed on the user_output I/O 
switch. (Default) 

READ RECORD OPERATION 

The ANSI PFM supports the iox_$read_record operation when the I/O switch is open 
for sequential_input. In general, format dependent logical records are extracted from 
physical tape blocks and written into the callers buffer area. As each tape block is 
exhausted, the ANSI PFM requests the mtape_ I/O module to read in the next tape 
block. This sequence continues until logical End of File is detected by the ANSI 
PFM, at which time error_table_$end_of_info is returned to the caller, and no further 
read_record requests will be accepted by mtape_ or the ANSI PFM until the current 
file is closed and another file is subsequently opened. If the callers buffer length is 
not long enough to contain the entire logical record, as much data as will fit in the 
specified buffer is returned and error_table_$long u _record is returned to the caller. In 
this case, the ANSI PFM will position to the next logical record. If in the course of 
reading logical records, an End of Volume condition is detected by the ANSI PFM, 
automatic volume switching is initiated, which if successful, will be transparent to the 
caller. 

WRITE RECORD OPERATION 

The ANSI PFM supports the iox_$write_record entry when the I/O switch is open for 
sequential_output. In general, data of the specified record length is extracted from the 
users buffer, formatted into logical tape records and written into a physical tape block 
buffer. As each tape block buffer is filled, the ANSI PFM requests mtape_ to queue 
up the full buffer for writing and return a pointer to the next buffer to fill. This 
sequence continues until either: (1) The I/O switch is closed or (2) an mtape_ 
"volume_status" or volume_set_status" control operation is requested to be processed. 
In both cases, if a partially filled buffer exists, it will be queued up for writing as a 
short block and all unwritten buffers will be requested to be written out to tape. If 
the I/O switch is being closed, the ANSI PFM now writes out the End of File trailer 
sequence. If during the course of writing tape blocks the End of Volume condition is 
detected, the ANSI PFM immediatly writes out the End of Volume trailer labels and 
requests a volume switch to mount the tape to contain the next file section. After the 
new tape volume has been successfully mounted, the ANSI PFM initiates the volume 
label and new file section header labels and then requests that the unwritten buffers 
at the time of the end of volume detection be written out to tape. At this time, the 
write_record operation being processed at the time of the End of Volume detection is 
resumed. 
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POSITION OPERATION 

The ANSI PFM supports the iox_$position operation when the I/O switch is opened 
for sequential_input. All positioning types legal for sequential_input are supported. 
(See the description of iox_$position earlier in this manual.) 

READ LENGTH OPERATION 

The ANSI PFM supports the iox_$read_length operation when the I/O switch is open 
for sequential_input. The read_length operation is implemented by actually reading the 
next logical record to determine its length, while discarding the actual data. After the 
length has been determined, backspace record position operation is executed to position 
to the location prior to the read_length operation. When executing read_length 
operations on spanned formatted records, or if the read_length operation is to 
determine the length of the first record of the next block, actual tape motion (i.e. 
read forward, and backspace block) may be necessary and will occur automatically. If 
a spanned record spans a volume boundary, volume switching is initiated both when 
doing the actual read operation and the backspace. 

CONTROL OPERATION 

The ANSI PFM supports all of the general mtape_ control operations described in the 
mtape_ I/O module description. There are no control operations that are specific to 
the ANSI PFM. 

CALLING SEQUENCE FOR USER LABEL PROCESSING ROUTINE 

In order to process user defined file labels when the "-label_entry" open description 
argument is used, the entry variable argument to the *'-iabel_entry" control argument 
must conform to the following calling sequence in order to be called properly by 
mtape_ and its Per-Format modules: 

del user_label_entry entry (ptr, char (*), fixed bin, 
fixed bin, fixed bin, fixed bin (35)); 

call user„label_entry (iocb_ptr, user_label_data, label_number 5 
label_type, file_section_number, code); 

where: 
iocb_ptr 

is a pointer to the I/O control block through which the mtape_ I/O module 
is attached. A user_label_entry routine may wish to know more information 
about the file for which it is processing user labels. This can be accomplished 
by calling the iox_$control entry with this iocb_ptr and executing the mtape_ 
T, file_status" control operation. 

user_label_data 

is the actual contents of the user label record to be processed (INPUT) or 
written (OUTPUT). The length of this field will be 76 characters on input and 
truncated to same on output. 
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label_number 

is the number of the user label record within the file label group. The ANSI 
standard allows from 1 to 9 user label records within a file label group (UHL1 
- UHL9, and UTL1 - UTL9). 

label_type 

is the encoded file label group type that the user_label_entry is being called to 
process label records for. Its possible values are as follows: 

1 = Beginning of file (BOF) label group 

2 = End of volume (EOV) label group 

3 - End of file (EOF) label group 

f ile_section_number 

is the section number of the file for which the user_label_entry routine is 
being called to process user labels for. For multivolume files, this would 
essentially be the number of the volume (the first volume on which a file 
resides being number 1) on which this file "section" resides. For single volume 
files, the file_section_number would always be a 1. 

code 

is a standard system error code. When writing user labels, the user_label_entry 
routine should set code to error_table_$end_of_info in order to tell the caller 
that no more user labels are to be written. Otherwise, the user_label_entry is 
called repeatedly to generate user label data until the maximum number of user 
labels have been written. 



SEARCHING FOR A FILE 

Before a file may be either created or read, its physical position within the volume 
set must be located. In the case of file creation, its physical position may be 
non-existent, but to ensure file set integrity all of the files in the file set must be 
searched to ensure its non-existence. To reduce physical tape searching to a minimum, 

+u« a xtct r>T7ik A :„ „ ~ — ♦ — „ i; _ 1. ~ j i;„<- _ c 1 

uic rwiiJi i i in m cuntfci i wmi uiuipt_ iimiii uuiia a iiiikcu uai ui i nc sci uicmucia, 

with adequate information in each element of the linked list to identify the file it 
represents and its physical position within the volume set. At the time of the first 
opening, the above mentioned linked list of file set members does not exist In this 
case, the volume set is searched sequentially forward until the desired file is found. 
As each file preceding the desired file is identified, a new element is added to the 
linked list of file set members, extracting file identity and format information from 
the file header and trailer labels, and obtaining the physical position of the file 
header from mtape_. On subsequent file openings, this linked list of file set members 
is searched first, and if the desired file is identified as being one of the elements, the 
volume set is positioned to the indicated position of the file header. If the desired 
file is not found in the linked list of file set members, then the volume set is 
searched forward from the position of the last identified file in the linked list, adding 
to the list as it proceeds in an attempt to find the desired file. 
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There are 6 open description control arguments which deal with identifying a file to 
be processed. These are: -append, -iast_file, -name, -next_file, -number and -replace. 
From reading their descriptions above, it can be seen that if some of them were used 
together, they would form an inconsistent identity for a file to be found. (e.g. If 
-last_file and -next_file were used together, they may or may not describe the same 
file.) In order to keep the set of file identity arguments consistent for any given file, 
certain rules are applied when the open description is parsed as follows: 

1. Open description arguments are parsed from left to right. 

2. Any default arguments and their associated values are parsed before the users open 

description is parsed. 

3. Control arguments and their associated values on the right take precedence over the 

same control argument and its value that preceded it. (e.g. In an open description 
which included "-name FILEX -name FILEY", the parsed result would be "-name 
FILEY".) 

4. Binary control arguments (e.g. -last_file) all have an associated antonym value (i.e. 

-no_last_file). As each binary control argument is parsed, it takes precedence and 
replaces any opposite control argument that preceded it. (e.g. In an open 
description which included "-last_file -no_last_file" the parsed result would be 
-no_last_file.) 

5. For each of the 6 file identity open description arguments, there are a certain set 

of control arguments with which it is mutually exclusive with and takes 
precedence over. The chart below illustrates this mutual exclusitivity: 

| -append | - 1 as t_f i 1 e | -name | -next_f i 1 e ] -number j -repl ace J 



-append 

-last_f i le 
-name 

-next_f i 1 e 
-number 
-repl ace 




CREATING A FILE 

When a file is created, an entirely new entity is added to the file set. There are two 
modes of creation: append and replace. In append mode, the new file is added to the 
file set immediately following the last (or only) file in the set. The process of 
appending does not alter the previous contents of the file set. In replace mode, the 
new file is added by replacing (overwriting) an existing file. The replacement process 
logically truncates the file set at the point of replacement, destroying all files (if any) 
that follow consecutively from that point. 

The file to be created may be identified explicitly by specifying the file name and/or 
number (with the -name and -number open description control arguments) either 
together or individually. If a -name and -number control arg appear in the same 
open description, they must identify the same file or an error will result. 

The file to be created may be identified implicitly by specifying one of the relative 
position control arguments, -append, -last_file or -next_file in an open description. 
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Implicit file replacement is also accomplished if the file to be created is identified as 
already existing. 

If the user wishes to explicitly specify creation by replacement, the particular file to 
be replaced must be identified. Associated with every file is a name (file identifier) 
and a number (file sequence number.) Either is sufficient to uniquely identify a 
particular file in the file set. The -number N and -replace STR control arguments, 
either separately or in conjunction, are used to specify the file to be replaced. If 
used together, they must both identify the same file; otherwise, an error is indicated. 

When the -number N control argument is specified, if N is less than or equal to the 
sequence number of the last file in the file set,, the created file replaces the file 
having sequence number N. If N is one greater than the sequence number of the last 
file in the file set, the created file is appended to the file set. If N is any other 
value, an error is indicated. 

The -format F, -record R and -block B control arguments, or their default values, 
are used to specify the internal structure of the file to be created. They are 
collectively known as structure attribute control arguments. 

When the —format F control argument is used, F must be one of the following 
format codes, chosen according to the nature of the data to be recorded. (For a 
detailed description of the various record formats, see "Record Formats" below.) 
fb for fixed-length records, blocked. 

Used when every record has the same length, not in excess of 99996 characters. 

db for variable length records, blocked. 

Used when records are of varying lengths, the longest not in excess of 99992 
characters. 

sb for spanned records, blocked. 

Used when the record length is fixed and in excess of 99996 characters, or 
variable and in excess of 99992 characters. In either case, the record length 
cannot exceed 1,044,480 characters. 

f for fixed -length records, unblocked. 

d for variable-length records, unblocked. 

s for spanned records, unblocked. 

u for undefined records. 

(records undefined in format). Each block is treated as a single record, and a 
block may contain a maximum of 99996 characters. 

NOTE: THE USE OF UNDEFINED RECORDS IS A NONSTANDARD FEATURE. 

Records recorded using U format may be irreversibly modified; therefore, the use of 
U format is strongly discouraged. (See "Block Padding" below.) 
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Unblocked means that each block contains only one record (f, d) or record segment 
(s). Blocked means that each block contains as many records (fb, db) or record 
segments (sb) as possible. The actual number of records/ block is either fixed (fb), 
depending upon the block length and record length, or variable (db, sb), depending 
upon the block length, record length, and actual records. Because of their relative 
inefficiency, the use of unblocked formats is discouraged. 

When the -record R control argument is used, the value of R is dependent upon the 
choice of record format. In the following list, amrl is the actual or maximum record 
length. 



F 


= fb 


f : 


R = amrl 


F 


= db 


d: 


amrl + k <= R <= 99996 


F 


= sb 


s: 


amrl <= R <= 1044480 


F 


= u: 




R is undefined 



(the -record control argument should not be used.) 



When the -block B control argument is used, the value of B is dependent upon the 
value of R. When the block length is not constrained to a particular value, the largest 
possible block length should be used. 

F = fb: B must satisfy mod (B,R) = 0 

F = f: B = R 

F = db: B >= R 

F = d: B = R 

F = sb | s: 18 <= B <= 99996 

F = u: amrl <= B <= 99996 



In every case, B must be an integer in the range 18 <= B <= 99996. 

NOTE: THE USE OF BLOCK LENGTHS IN EXCESS OF 2048 CHARACTERS 
VIOLATES THE ANSI INTERCHANGE STANDARD AND THEREFORE 
SHOULD NOT BE USED IN AN INTERCHANGE ENVIRONMENT. 



READING A FILE 



The open description needed to read a file is less complex than the description used 
to create it. When a file is created, the structure attributes specified in the open 
description are recorded in the file's header and trailer labels. These labels, which 
precede and follow each file section, also contain the file name, sequence number, 
block count, etc. When a file is subsequently read, all this information is extracted 
from the labels. Therefore, the open description need only identify the file to be 
read; no other control arguments are necessary. Any of the 6 file identification open 
description control arguments (See "Searching For a File" above.) may be used to 
identify the file to be read. 
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OUTPUT OPERATIONS ON EXISTING FILES 

Three output operations can be performed on an already existing file: extension, 
modification, and generation. As their functions are significantly different, they are 
described separately below. They do, however, share a common characteristic. Like the 
replace mode of creation, an output operation on an existing file logically truncates 
the file set at the point of operation, destroying all files (if any) that follow 
consecutively from that point. 

EXTENDING A FILE 

File extension is the process of adding records to a file without in any way altering 
the previous contents of the file. 

Because all the information regarding structure, length, etc. can be obtained from the 
file labels, the open description need only specify that an extend operation is to be 
performed on a particular file. The previous contents of the file remain unchanged; 
new data records are appended at the end of the file. If the file to be extended does 
not exist, an error is indicated. 

The file to be extended is identified by using any of the 6 open description file 
identifying control arguments. (See "Searching For A File" above.) 

Recorded in the labels that bracket every file section is a version number, initially set 
to 0 when the file is created. The version number is used to differentiate between 
data that have been produced by repeated processing operations (such as extension). 
Every time a file is extended, the version number in its trailer labels is incremented 
by 1. When the version number reaches 99, the next increment resets it to 0. 

Any structure attribute open description control arguments specified by the user are 
ignored when extending a file. 

MODIFYING A FILE 

It is occasionally necessary to replace the entire contents of a file, while retaining the 
structure of the file itself (as recorded in the header labels). This process is known as 
modification. 

Because all necessary information can be obtained from the file labels, the open 
description need only specify that a modify operation is to be performed on a 
particular file. If a file to be modified does not exist, an error is indicated. The 
entire contents of the file are replaced by the new data records. The version number 
in the trailer labels of a modified file is incremented by 1, as described above. 

Any structure attribute open description control arguments specified by the user are 
ignored when modifying a file. The file to be modified is identified as above. 
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GENERATING A FILE 

Recorded in the labels that bracket every file section is a generation number, initially 
set to 0 when the file is created. The generation number is used to differentiate 
between different issues (generations) of a file, that all have the same file identifier. 
The duplicate file identifier rule (see "Creating a File" above) precludes multiple 
generations of a file from existing simultaneously in the same file set. 

The generation number is a higher order of differentiation than the version number, 
that is more correctly known as the generation version number. While the process of 
modification or extension does not change the generation number, the process of 
generation increments the generation number by 1, and resets the version number to 0. 
The generation number can only be incremented by rewriting the header labels, and it 
is in this respect that the processes of generation and modification differ. 

Producing a new generation of a file is essentially the same as creating a new file in 
place of the old; however, the file identifier, sequence number, and structure attributes 
are carried over from the old generation to the new. The open description need only 
specify that a generation operation is to be performed on a particular file. If the file 
to be generated does not exist, an error is indicated. An entirely new generation of 
the file is created, replacing (and destroying) the previous generation. The generation 
number is incremented by 1; the version number is reset to 0. When the generation 
number reaches 9999, the next increment resets it to 0. 

Any structure attribute open description control arguments specified by the user are 
ignored when generating a file. The file to be generated is identified as above. 

ENCODING MODE 

The ANSI PFM makes provision for three data encoding modes: ASCII, EBCDIC, and 
binary. Because the Standard requires that the data in each record be recorded using 
only ASCII characters, the default data encoding mode is ASCII. File labels are always 
recorded using the ASCII character set. 

When a file is created, the -mode STR can be used to explicitly specify the encoding 
mode, where STR is the string ascii, ebcdic, or binary. The default is the string ascii. 

If STR is the string ascii, the octal values of the characters to be recorded should be 
in the range 000 <= octal_value <= 177; characters in the range 200 to 377 are not 
invalid, but recording such characters is a nonstandard feature; characters in the range 
400 to 777 cause an unrecoverable I/O error. If STR is the string ebcdic, the octal 
values of the characters to be recorded MUST be in the range 000 to 177. (See the 
ascii_to_ebcdic_ subroutine for the specific ASCII to EBCDIC mapping used by the 
ANSI PFM.) If STR is the string binary, any octal value can be recorded. 

Like its predecessor, the tape_ansi_ I/O module, the ANSI PFM records the data 
encoding mode in a portion of the file labels reserved for system-defined use. When 
the file is subsequently read, the encoding mode is extracted from the file labels, so 
the -mode STR control argument need not be specified. 
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FILE EXPIRATION 

Associated with every file is a file expiration date, recorded in the file labels. If a 
file consists of more than one file section, the same date is recorded in the labels of 
every section. A file is regarded as "expired" on a day whose date is later than or 
equal to the expiration date. Only when this condition is satisfied can the file (and 
by implication, the remainder of the file set) be overwritten. Extension, modification, 
generation, and the replace mode of creation are all considered to be overwrite 
operations. 

The expiration date is recorded in Julian form; i.e., yyddd, where yy are the last two 
digits of the year, and ddd is the day of the year expressed as an integer in the 
range 1 <= ddd <■ 366. A special case of the Julian date form is the value "00000" 
(always expired). 

The expiration date is set only when a file is created or generated. Unless a specific 
date is provided, the default value "00000" is used. The -expires date control argument 
is used to specify an expiration date, where date must be of a form acceptable to the 
convert_date_to_binary_ subroutine; the date may be quoted and contain embedded 
spaces; Julian form, including "00000", is unacceptable. Because overwriting a file 
logically truncates the file set at the point of overwriting, the expiration dale of a file 
must be earlier than or equal to the expiration date of the previous file (if any); 
otherwise, an error is indicated. 

If an attempt is made to overwrite an unexpired file, the user is queried for explicit 
permission. The -force control argument unconditionally grants permission to overwrite 
a file without querying the user, regardless of "unexpired" status. 

PROCESSING INTERCHANGE FILES 

The Standard makes provision for recording record format, block length, and record 
length in specific fields most notably (volume name and file name) of the HDR2 file 
label. In addition, the ANSI PFM records the encoding mode in a portion of the 
HDR2 label reserved for system-defined use. Because the Standard restricts the 
encoding mode to ASCII, there is no "standard" label field reserved for recording 
encoding mode. Therefore, if a foreign interchange file (a file not created by this 
Per-Format module, or its predecessor, the tape_ansi_ I/O module) uses an encoding 
mode other than ASCII, the -mode STR control argument must be used to specify the 
mode. 

File sets are almost always recorded with HDR2 file labels, with the exception of 
those created by "primitive" systems at implementation levels 1 or 2. (See the 
Standard for a description of the facilities supported at different implementation 
levels.) It is therefore rarely necessary to explicitly specify record format, block 
length, or record length when interchange files are read, extended, modified, or 
generated. If, however, a file does lack HDR2 labels, explicit attribute specification or 
the application of the appropriate defaults is required. 
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ASCI I SUBSET 

The Standard suggests that the characters that comprise certain alphanumeric label 
fields be limited to a 56-character subset of full ASCII. Furthermore, it is suggested 
that these fields should not contain embedded blanks, nor should they consist entirely 
of blanks. In particular, the user need only consider file identifiers and volume 
names. 

The 56-character subset includes: 

uppercase letters: ABCDEFGHIJKLMNOPQRSTUVWXYZ 
digits: 0123456789 

speciallcharacters: <space> ! "%&'()* + ,- . / : ;< = >? 

These characters were chosen from the center four columns of the code table specified 
in USA Standard Code for I nf or mat ion Interchange, ANSI X3.4-1968, except for 
position 5/15 (the underscore (_) character) and those positions where there is 
provision for alternate graphic representation. 

The limitation to this subset is intended to provide maximum interchangeability and 
consistent printing, especially for international interchange. 

RECORD FORMATS 

ANSI files are structured in one of three record formats: F, D, or S. In addition, 
the ANSI PFM provides for a fourth format, U. When a file is created, its record 
format should be chosen in accordance with the nature of the data to be recorded. 
For example, data consisting of 80-character card images is most economically recorded 
in F format, fixed-length records. Data consisting of variable length text lines, such 
as PL/ 1 source code produced by a text editor, is best recorded in D format, 
variable-length records. Data of arbitrary length (that could exceed the maximum 
block size) must be recorded in S format, spanned records, so that a lengthy datum 
can span several blocks. 

F, D, and S format files are either blocked or unblocked, blocked being the normal 
case. Each block of an unblocked file contains just one record, whereas each block of 
a blocked file can contain several records. Blocking can provide a significant savings 
of processing time, because several records are accessed with a single physical tape 
movement. Furthermore, as blocks are separated by distances of blank tape, blocking 
reduces the amount of tape needed to contain a file. 



F Format 

In F format, records are of fixed (and equal) length, and files have an integral 
number (N) of records per block. If the file is unblocked, N is equal to 1 and the 
record length (R) is equal to the block length (B). If the file is blocked, N is greater 
than 1 and B is equal to (R * N). N is known as the blocking factor. 
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For example, if R is equal to 800 and B is equal to 800, then the file is unblocked 
and each block contains just one record. 



data | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



block | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



If R is equal to 800 and B is equal to 2400, then the file is blocked, the blocking 
factor is 3, and each block contains three records. 



data | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



block | 800 | 800 | 800 | | 800 | 800 j 800 | 



The ANSI standard for F format records permits recording a short block only when 
the last block of a blocked file contains fewer than N records and there are no more 
records to be written when the file is closed. 

There are two special cases in which a datum is padded out to length R. The first 
case is that of iobl (the iox_$write_record I/O buffer length Gobi); i.e., the number 
of characters to be written) equals 0: a record of R blanks is written. When such a 
record is subsequently read, it is interpreted as a record of R blanks, and not as a 
zero-length record. The second case is that of 0 < iobl < R: the record is padded 
on the right with blanks to length R, and the padded record written. When such a 
record is read, the original characters plus the padding are returned. The case of iobl 
greater than R is in error. 

NOTE: THE ANSI STANDARD PROHIBITS RECORDING A FIXED-LENGTH 
RECORD THAT CONSISTS ENTIRELY OF CIRCUMFLEX H CHARACTERS. 



D Format 

In D format, records and therefore blocks may vary in length. Each record is 
preceded by a four-character record control word (RCW) that contains the total 
record length (the length of the data plus the length of the RCW itself). 

D format files have an integral number (n) of records per block. If blocked, R is 
less than or equal to B. For blocked records, the number of records per block varies 
indirectly with the size of the records. 
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If R = B = 804 and the file is unblocked, records of up to 800 characters can be 
written, and each block contains one record. 



data 



| 375 ! ! 280 | | 610 || 



800 





3 






2 






6 






8 




block 


7 


375 




8 


280 




1 


610 




0 


800 




9 






h 






k 






k 





If R equals 804, B is slightly greater than or equal to 804, and the file is blocked, 
records of up to 800 characters can be written. 



data 



| 375 || 280 | | 610 || 



800 





3 




2 






6 






8 


block 


7 


375 


8 


280 




1 


610 




0 




9 




k 






if 






h 



800 



Each block can contain a maximum of 201 zero-length records (a record written as a 
four-character RCW containing 0004). 



S Format 

In S format, a single record is formatted as one or more record segments. A record 
segment contains either a complete record, the initial portion of a record, a medial 
portion of a record, or the final portion of a record. No two segments of the same 
record can be contained in the same block, but a block may contain the segments of 
several different records. The maximum record length is limited only by the maximum 
size of a storage system segment, currently 1,044,480 characters. 

S format files have an integral number of record segments per block. If the file is 
unblocked, each block contains only one record segment; if blocked, the number of 
record segments per block is variable. In either case, R and B are independent of one 
another. 



Each record segment begins with a five-character segment control word (SCW). The 
SCW 7 contains a four-character record segment length, that includes the length of the 
SCW itself. The SCW also contains a one-character record segment code, that indicates 
if the segment contains a complete record, or an initial, medial, or final portion. 
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In the examples below, R equals 1000 and B equals 800. In the first example, the file 
is unblocked 



data 



200 



1+00 



1000 





2 






k 






8 






2 




block 


0 


200 




0 


hOO 




0 


795 




l 


205 




5 






5 






0 






0 





In the next example, the file is blocked 



data 



200 



i*00 



1000 





2 






U 






1 






8 






2 




record 


0 


200 




0 


400 




9 


185 




0 


795 




5 


20 


segment 


5 






5 






0 






0 


































2 




h 




1 






8 






2 




block 


0 


200 


0 


hOO 


9 


185 




0 


795 




5 


20 




5 




5 




0 






0 











U format files contain records that do not conform to either F, D, or S format. A 
U format file is always unblocked. The record length is undefined, and B is greater 
than or equal to iobl. Blocks may vary in length. 

NOTE: THE USE OF U FORMAT IS A NONSTANDARD FEATURE 



The ANSI block padding convention permits a block (in ANY format) to be padded 
out to any length with circumflex characters ("0 , according to the requirements of the 
system that produces the file. These characters are ignored on input. (See "Block 
Padding" below.) In U format, block padding can lead to an ambiguity; i.e., are 
trailing circumflexes indeed pad characters, or are they actually valid data within the 
nonpadded portion of the block. The Standard suggests that an entire U format block 
be treated as a single record. In conformance with this suggestion, the ANSI PFM 
considers trailing circumflexes to be valid data. 
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The special case of writing a record where iobl is less than 20 characters produces a 
block padded to length 20 with circumflex characters. 



data | 60 | | 127 I I 16 I I ] 56 



block | 60 | | 127 | | 20 | | 156 



BLOCK PADDING 

The Standard makes provision for extending the recorded length of a block beyond 
the end of the last (or only) record whenever such padding is deemed necessary or 
advisable. Padding characters are not considered when computing an RCW or SCW 
length. Unlike its predecessor, the tape_ansi_ I/O module who required that all blocks 
be padded out to modulo 4 characters, the ANSI PFM only requires padding to 
modulo 4 characters, if the file is being recorded in binary mode. In which case the 
ANSI PFM automatically pads every block to the correct length, using from 1 to 3 
circumflex characters. In addition, the Standard does not permit recording a block of 
fewer than 18 characters. To conform with this requirement, the ANSI PFM pads any 
block containing fewer than 20 characters out to length 20. 

As long as F, D, or S format is used, the presence or absence of block padding 
characters in a particular block is user-transparent. If U format is used, it is the 
responsibility of the user to detect and ignore any pad characters that may be 
generated. 

VOLUME INITIALIZATION 

The Standard requires that all volumes be initialized with a VOL1 label and dummy 
file before they are used for output. The ANSI PFM provides a semiautomatic volume 
initialization mechanism that performs this operation as an integral part of the output 
function. The rules that govern permission to initialize a volume are complex, and 
permission to initialize under most circumstances is specifically denied (by the 
Standard) to the application program. The ANSI PFM's mechanism strikes a balance 
between outright denial and absolute ease. 

. BUFFER OFFSET 

The Standard provides for each block of a file being prefixed by from I to 99 

characters of prefix information, known as the buffer offset. The buffer offset length 

is recorded in the HDR2 label. If an input file has block prefixes, and the block 

length is explicitly specified, it must be incremented by the buffer offset length. This 
calculation should made after the block length has been determined using the normal 
block-record relationship rules. 
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The ANSI PFM will record a block prefix which contains block number and block 
length information, only if the -buffer_offset open description argument is specified. 
When reading a file, the block prefix area, if it exists, is ignored by the ANSI PFM, 
unless the file has been identified as being recorded by the ANSI PFM. If this is the 
case, the block prefix area (described in the -buffer_offset open description argument 
above), is used by the ANSI PFM for positive block position and length comparisons. 

CONFORMANCE TO STANDARD 

The ANSI PFM conforms to the ANSI standard for level 4 implementations with the 
following three exceptions: 

1. Volume Initialization — The ANSI PFM has a permission-granting mechanism 

that can be controlled by the application program. 

2. Volume and File Accessibility — On input, the ANSI PFM always grants 

permission to access. On output, the access control fields in the VOL1 and 
HDR1 labels are always recorded as blank (" "). 

3. Overwriting Unexpired Files — The ANSI PFM has a permission-granting 

mechanism that can be controlled by the application program. 

LABEL PROCESSING 



VOL1 

The label is processed on input and output. The owner-identifier field, character 
positions (CP) 38 to 51, holds a three-character volume authentication code, in 
character positions 38 through 40 and the character string "MULT001" in character 
positions 41 through 46. 

UVL1 

This label is processed on output and ignored on input. The contents of the 
UVL1 label is meant to be used by Site/Tape administrators for historical 
information about tape usage at their particular site. The contents of the UVL1 
label are as follows: 



CP 01 to 04 - Label identifier ("UVLl"). 

CP 05 to 07 - Volume authentication code. (The same as VOL1 label 

CP 38 to 40). 

CP 08 to 13 - Julian Creation date (" YYDDD"). 

CP 14 to 17 - Unused (" "). 

CP 18 to 49 - Site installation code. 

CP 50 to 80 - Person.Project Instance of creator of tape. 



UVL2 - UVL9 

These labels are not written on output, and ignored on input. 
HDR1/EOF1/EOV1 

The labels are processed on input and output. The system-code field, CP 61 to 
73, is recorded as "MULTICS ANSI2". 
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HDR2/EOF2/EOV2 

The labels are processed on input and output. The reserved-f or-system-use field, 
CP 16 to 50, is recorded as follows: 

CP 16 to 47 - full 32-character volume name of next volume 

(EOV2 only) 
CP 48 - blocking attribute (all) 

"0" = unblocked; "1" = blocked 
CP 49 - data encoding mode (all) 

"1" = ASCII, 9 mode 

"2" = EBCDIC, 9 mode 

"3" - binary 

HDR3/EOF3/EOV3 - HDR9/EOF9/EOV9 

These labels are not written on output and are ignored on input. 

UHLa/UTLa 

These labels are processed on output and input only if the "~label_entry" open 

description argument is given. Otherwise, not written on output and ignored on 
input 



Name: audit 

The audit_ I/O module is used to monitor input and /or output directed over a given 
stream I/O switch. Entries of various kinds are appended to the audit file in response 
to input and output on the specified switch. These are described in detail below. See 
the Commands manual for descriptions of the related commands attach_audit, 
detach_audit, and display_audit_file, and for a description of the audit editor requests. 

Entry points in this module are not called directly by users; rather, they are accessed 
through the I/O system. 

ATTACH DESCRIPTION 

audit_ switch_name {-control_args} 

ARGUMENTS 

switch_name 

is the name of an existing I/O switch that is to be monitored. 
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-truncate, -tc 

truncates the audit file, if it already exists. The default is to extend the audit 
file. 

-pathname path, -pn path 

specifies the pathname of the new. audit file. The default pathname is 
[home_di r]> [date] .audi t, where date is the date (in the form MM/DD/YY) 
returned by the date_time_ subroutine at the time of attachment. 

NOTES 

The attachment of audit_ does an implicit open of the switch. Attachment is 
simplified by use of the attach_audit command. 

MODES OPERATION 

Modes for the audit_ I/O module are listed below. Some modes have a complement, 
indicated by the circumflex character (~), that turns the mode off. 

audit_trace, A audit_trace 

traces all control and mode calls to the module. An entry with a TC or TM 
identifier (for a control call or mode call, respectively) is placed in the audit file. 
This entry describes the contents of the given call. The default is off. 

audit_input, A audit_input 

turns on auditing for input lines. The default is on. 

audit_output, A audit_output 

turns on auditing for output lines. The default is on. 

audit_edit, A audit_edit 

enables audit editing. The default is on. If audit_edit is off, the auditing requests 
are not recognized. (See the attach_audk command for a discussion of auditing 
requests.) 

audi t_transparent, A audit_transparent 

turns off auditing of auditing requests and editing requests, as well as their 
results. EL entries are still audited (see "Audit File" below). The default is off. 

audit_suspend, A audit_suspend 

disables all audit capabilities. The default is off. 

audit_meter, A audit_meter 

writes a metering record before each entry in the file containing the actual time 

of the metering, the incremental CPU time since the last metering, and the 

incremental page faults since the last metering. The default is off. 
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audit_trigger=X 

sets the auditing request trigger to the character specified by X. The default is an 
exclamation point (!). 

audit_file_size=N 

sets the maximum number of records for the audit file to N. When the 
maximum is reached, the file is scrolled; i.e., it is treated as a circular buffer of 
N records. If N is the character string "unlimited", the file will grow without 
limit. The default is unlimited. 

audi t_use_edi tor_prompt, A audi t_use_edi tor_prompt 
turns prompting on or off in the audit editor. 

audit_editor_prompt=STR, audit_epstr=STR 

sets the audit editor prompt string to STR. The audit editor prompt has the 
default appearance "audit editor: or, if the number of recursive invocations 
of the editor is greater than 1, "audit editor(N): ", where N is the depth 
of the current invocation. This string is used as an ioa_ control string, with the 
arguments being: a bit which is on if the level is greater than 1; and, the level. 
The default string is "Vaudit edi tor~[ (~d) ~] :~2x". 

Note that modes not preceded by "audit_" are passed on to the I/O module being 
audited. 

CONTROL OPERATION 

This I/O module supports the following control orders: 

audit_truncate 

truncates the audit file. 

audit_modes 

returns the current audit modes in a char (256) varying string pointed to by 
info_ptr. 

OTHER OPERATIONS 

The only other operation that is supported is the position operation, which is passed 
on to the audited I/O module. 
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THE AUDIT FILE 

The audit file, by default, has the pathname: 

>udd>Project_id>Person_id>[date] .audi t 

where date is the first eight characters (the date portion) returned by the date_time_ 
subroutine, and is of the form: mm/dd/yy. This pathname can also be specified 
using active functions: 

[home_d i r]>[date] .aud i t 
The default audit file size is unlimited, and the audit file can become a multisegment 



The entry type identifiers are: 



EL 


edit line, returned from audit editor. 


IC 


result of a get_chars. 


IL 


result of a getjine. 


M 


metering data. 


OC 


result of a put_chars. 


TC 


control request trace. 


TM 


mode request trace. 



AUDIT REQUESTS 

The audit requests are always recognized when auditing is on. The three character 



request sequence is the trigger character followed b v the desired r An uest followed b lr a 



new line. However, when an unrecognized request is given, the entire line is treated 
as a regular input line with no special processing. The default trigger character is an 
exclamation mark ("!"). The requests are: 



file. 



print "audit" and which of input and output is being audited. 



!? 



print a brief description of available audit requests. 



!e 



enter the audit editor. 



!E 



enter the audit editor, with the input line processed as edit requests. 



!a 



abbrev expand the input line. 
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!r replay the input line. That is, display the input line without a new line. 

Further input up to the next new line is appended to the redisplayed input 
This is the input line which is passed through the audit_ I/O module. 

!t instructs the audit_ I/O module not to log the input line, i.e., to make it 

transparent 

!d delete the line. It prevents the input line from ever being seen. 

!n no operation. The input line to which this is appended is simply passed 

through the audit. I/O module. 



Name: bisync_ 

The bisync_ I/O module performs stream I/O over a binary synchronous communications 
channel. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

ATTACH DESCRIPTION 

bisync_ device {-control_args} 

ARGUMENTS 

device 

is the name of the communications channel to be used for communications. 
CONTROL ARGUMENTS 
-ascii 

uses the ASCII bisync protocol. This is the default 
-bid_limit N 

sets to N the number of times a line bid is retried. The default is 30 times, 
-breot 

causes the get_chars operation to return any block of data ending with an 
end-of -transmission (EOT) character (see "Get Chars Operation" below). 

-bretb 

causes the get_chars operation to return any block of data ending with an 
end-of-text block (ETB) character. The default is to return only blocks ending 
with an end-of-text control character (ETX) or an intermediate text block (ITB) 
control character (see the discussion of the get_chars operation below). 
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-ebcdic 

uses the EBCDIC bisync protocol, 
-hangup 

causes an automatic hangup when the switch is detached. 
-multi_record {N} 

specifies that blocking of logical records is done by the I/O module. If specified, 
N is the maximum . number of records per block. If N is not given, the number 
of records per block is as many as fit 

-nontransparent 

uses the nontransparent bisync protocol. 

-output_etb 

causes output records to the FNP channel to be terminated with the ETB 
character instead of with the default ETX characters. The caller of the device 
module (ibm3780_, ibm2780_, etc.) is expected to signal the termination of the 
transmission of a file (SSF or MSF) by passing down a "runout" control order. 
This will cause the device module and bisync_ to flush out any data being held 
in internal buffers. The bisync_ module will then transmit a null message with an 
ETX character. Subsequent calls to the bisync_put_chars entry will resume the 
transmission of records with the ETB character until the next runout control 
order. 

output_etx 

causes all output records to be terminated with the ETX characters. (Default) 
-size N 

sets to N the number of characters to be transmitted in each bisync block. The 
default is 256 characters. 

-transparent 

uses the transparent bisync protocol. This is the default. 

i: xt 

iLU_iinni LV 

sets to N the maximum number of TTDs that are sent before sending an EOT. 
The default is 30 TTDs. 

-ttd_time N 

sets to N the number of seconds of temporary text delay (TTD) transmissions if 
output is delayed. The default is two seconds. 

OPEN OPERATION 

The bisync_ I/O module supports the stream_input, stream_output, and stream_input_output 
opening modes. 
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PUT CHARS OPERATION 

The put_chars entry splits the data to be written into blocks according to the -size 
control argument in the attach description. The appropriate bisync control characters 
are added to the beginning and end of each block. Each block except the last is 
transmitted with an ETB control character at the end. The last block is transmitted 
with an ETX control character at the end. 

GET CHARS OPERATION 

The get_chars entry reads and decodes bisync blocks, removes the control characters, 
and returns the message text to the caller's buffer. 
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Characters are returned up to the next logical bisync break character. Normally this is 
ETX. If -bretb is specified in the attach description, ETB is also considered to be a 
break character. If -multi_record is given, the interrecord ITB characters are also 
considered to be break characters. In addition, if -breot is specified, 
error_table_$end_of_info is returned when an EOT is read. 

GET LINE OPERATION 

The get_line entry reads and decodes bisync blocks, removes the control characters, 
and returns the message text to the caller's buffer. Characters are returned until either 
a newline character is placed in the buffer or the buffer is filled. The get_line entry 
does not distinguish between blocks ending in ETB or ITB and blocks ending in ETX. 

CONTROL OPERATION 

Several of the control operations supported by the bisync_ I/O module are identical 
to those supported by the tty_ I/O module and are documented there. They include: 

abort 

event_info 

hangup 

read_status 

resetread 

resetwrite 

write_status 

The following additional control operations are supported by this I/O module. 
end_write_mode 

causes the I/O module to block until all outstanding output has been written. 
get_bid_limit 

where info_ptr points to a fixed binary bid limit that is set either to the value 
specified at attach or in the last set_bid_limit order. 

get_bsc_modes 

returns the structure described under set_bsc_modes. 
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get_chars 

performs a get_chars operation and returns additional information about the input. 
The info_ptr points to a structure of the following form: 

del 1 get_chars_i nf o, 
2 buf_ptr ptr, 
2 buf_len fixed bin (21), 
2 data_len fixed bin(21), 
2 hbuf_ptr ptr, 
2 hbuf_len fixed bin (21), 
2 header_len fixed bin(21), 
2 flags, 

3 etx bi t (1) unal , 

3 etb bit (1) unal , 

3 soh bi t (1) unal , 

3 eot bi t (1) unal , 

3 pad bi t (32) unal ; 

where: 

buf_ptr, buf_len 

define an input buffer for the text of the message. (Input) 

data_len 

is set to the number of characters of text read. (Output) 

hbuf_ptr, hbuf_len 

define an input buffer for the header of the message. (Input) 

header_len 

is set to the header's length in characters. (Output) 

etx 

indicates that text is terminated with an ETX character. (Output) 

etb 

indicates that text is terminated with an ETB character. (Output) 

soh 

indicates that the data includes a header. (Output) 

eot 

indicates that an EOT is received. (Output) 

pad 

is unused space in this structure. (Output) 

get_multi_record_mode 

where info_ptr points to a fixed binary record count This order returns the 
multirecord record count A 1 indicates single-record mode. 
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get_size 

where info_ptr points to a fixed binary buffer size and returns the current size. 
hangup_proc 

sets up a procedure to be called if the communications channel hangs up. The 
hangup_proc input structure has the following form: 

del 1 hangup_proc aligned, 

2 entry entry variable, 

2 datap ptr , 

2 prior fixed bin; 

where: 
entry 

is the entry to call when a hangup is detected, 
datap 

is a pointer to data for the hangup procedure, 
prior 

is the ipc_ event call priority to be associated with hangup notification. 

runout 

has meaning only in multirecord mode and writes the current partially filled 
block. 

send_nontransparent_msg 

writes the data specified in nontransparent bisync mode, regardless of the current 
transparency mode. This order is used to send short nontransparent control 
sequences while in transparent mode. The info_ptr points to a structure of the 
following form: 

del 1 order_msg, 

2 data_len fixed bin, 

2 data char (order_msg .data_l en) ; 



set_bid_limit 

where info_ptr points to a fixed binary bid limit to replace the bid_limit 
specified in the attach description. 
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set_bsc_modes 

where info_ptr points to a structure of the following form: 

del 1 bsc_modes, 

2 transparent bit(l) unal , 
2 ebedic bi t (1) unal , 
2 mbz bi t (34) unal ; 

The setting of the transparent and ebedic bits then replaces the values specified in 
the attach description. 

set_multi_record_mode 

where info_ptr points to a fixed binary record count. If the count is 1, the I/O 
module enters single-record mode; otherwise, multirecord mode is entered, and the 
count specifies the maximum number of records per block. Zero (or a null 
info_ptr) specifies no fixed limit; i.e., as many Tecords as fit are blocked. 

set_size 

where info_ptr points to a fixed binary buffer size. This new size replaces the 
size specified in the attach description. It cannot be larger than the size 
originally specified in the attach description. 



Name: cross ring 

The cross_ring_ I/O module allows an outer ring to attach a switch to a preexisting 
switch in an inner ring, and to perform I/O operations by forwarding I/O from the 
attachment in the outer ring through a gate to an inner ring. The cross_ring_ I/O 
module is not called directly by users; rather the module is accessed through the I/O 
system. 

ATTACH DESCRI PTlQN 

cross_ring_ switch_name N 
ARGUMENTS 
switch_name 

is a previously registered switch name in ring N. 

N 

is a ring number from 0 to 7. 
OPENING 

The inner ring switch may be open or not. If not open, it will be opened on an 
open call. All modes are supported. 
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CLOSE OPERATION 

The inner switch is closed only if it was opened by cross_ring_. 
OTHER OPERATIONS 

All operations are passed on to the inner ring I/O switch. 
NOTES 

This I/O module allows a program in an outer ring, if permitted by the inner ring, 
to use I/O services that are available only from an inner ring via cross_ring_io_$allow_cross. 
By the use of the cross_ring_io_$allow_cross subroutine a subsystem writer is able to 
introduce into an outer ring environment many features from an inner ring, thereby 
tailoring it to fit the user's specific needs. 

The switch in the inner ring must be attached by the inner ring before cross_ring_ 
can be attached in the outer ring. 



Name: discard 

The discard I/O module provides a sink for output and a no-op for input All 
output operations are supported and return a 0 error code, but discard any data. All 
input operations are supported and return either error_table_$end_of_info or 
error_table_$no_record as described below. The control and modes operations are also 
supported as no-ops. 

Entries in the module are not called directly by users; rather the module is accessed 
through the I/O system. 

ATTACH DESCRIPTION 

The attach description has the following form: 

di scard_ 

No options are allowed. 

LIST OF OPENING MODES 

This module supports the following opening modes: 

stream_input 

stream_output 

stream_input_output 

sequential_input 

sequential_output 

sequential_input_output 
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sequential_update 

keyed_sequential_input 

keyed_sequential_output 

keyed_sequential_update 

direct_input 

direct_output 

direct_update 

CONTROL OPERATION. 

This module supports the control operation in all opening modes. All orders are 
accepted; but they have no effect. A 0 error code is always returned, and the 
structure pointed to by the info pointer argument is not changed. 

MODES OPERATION 

This module supports modes operation in all opening modes. It always returns a null 
string for the old modes and a 0 error code. 

GET CHARS, GET LINE, AND READ RECORD OPERATIONS 

These operations always set the returned length to 0 and the error code to 
error_table_$end_of _inf o. 

PUT CHARS AND WRITE RECORD OPERATIONS 

These operations simply set the error code to 0 and returns. 

POSITION OPERATION 

This operation simply sets the error code to 0 and returns. 
DELETE OPERATION 

This operation sets the error code to error_table$no_record and returns. 
READ AND SEEK KEY OPERATIONS 

These operations set the returned length to 0 and the error code to error_table_$no_record. 
READ LENGTH OPERATION 

This operation sets the returned length to 0 and the error code to error_table_$no_record. 
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NOTES 

This I/O module implements all of the indicated operations in each opening mode. 
(See "Opening Modes and Allowed Input/Output Operations" in Section 5 of the 
Multics Programmer's Reference Manual, Order No. AG91). 



Name: gll5 

The gll5_ I/O module performs stream I/O to a remote I/O terminal that has the 
characteristics of the Honeywell Level 6 remote batch facility (G115 type). The 
hardware options currently supported are defined by the control arguments described 
below. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

ATTACH DESCRIPTION 

gll5_ -control_args 

CONTROL ARGUMENTS 

The following control arguments are optional, with the exception of -comm, -device, 
and -tty: 

-ascii 

uses the ASCII character set This is the default This argument is accepted for 
compatibility with other terminal I/O modules. 

-auto_call N 

specifies the phone number, N, to be called via the auto call unit on the 
specified communications channel. 

-comm STR 

uses the communications I/O module specified by STR. Currently, the only 
permissible value for STR is "rci". This argument is required for compatibility 
with all other I/O modules used by the I/O daemon. 
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-device STR 

attaches the subdevice specified by STR. STR can be printer, punch, reader, or 
teleprinter. 

-physical_line_length N, -pll N 

specifies the physical line length, N, of the output device. This argument is 
accepted for compatibility with other terminal I/O modules. 

-terminal_type STR, -Up STR 

STR specifies the terminal type whose conversion, translation, and special tables 
defined in the user or system terminal type table (TTT) are used to convert and 
translate input and output to and from the device. If not specified, no conversion 
or translation is performed. See "Notes" below. 

-tty STR 

connects the remote I/O terminal to the communications channel named STR. 
OPEN OPERATION 

The gll5_ I/O module supports stream_input, stream_output, and stream_input_output 
opening modes. 

PUT CHARS OPERATION 

The put_chars entry blocks the data to be written into blocks of up to 324 characters 
and transmits them to the specified communications channel. 

GET CHARS OPERATION 

The get_chars entry reads blocks of up to 324 characters and returns the number of 
characters requested up to the next record separator. 

CONTROL OPERATION 

This I/O module supports all the control operations supported by the tty_ I/O 
module, plus the following: 

end_write_mode 

prevents the gll5_ module from returning until all outstanding output has been 
written to the attached channel. 

hangup_proc 

sets up a procedure to be called if the communications channel hangs up. The 
hangup_proc structure has this form: 

del 1 hangup_proc aligned, 

2 entry entry variable, 

2 datap ptr, 

2 prior fixed bin; 
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where: 



entry 



is 



the entry to call when a hangup is detected. 



datap 



is 



a pointer to data for the hangup procedure. 



prior 



is 



the ipc_ event call priority to be associated with hangup notification. 



reset 



sets the edited mode of output conversion. 



runout 



transmits any data stored in the output buffer. There is no input structure. 
select_device 

selects the subdevice (printer, punch, or teleprinter) to which output is next 
directed. The input structure is of the form: 

del device char (32) ; 
MODES OPERATION 

This I/O module supports the rawi and rawo modes. It also supports the nonedited 
and default modes, which set and reset the edited output conversion, if it has been 
enabled by the -terminal_type control argument. 



The only allowable values in the output conversion table are 00 and any values greater 
than 16. All values defined in the description of the tty_ I/O module are allowed for 



length. 



Name: hasp host 

The hasp_host_ I/O module simulates record-oriented I/O to a single device of a 
workstation while communicating with a host system using the HASP communications 
protocol. See "Notes" below. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 



NOTES 
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This I/O module must be attached to a subchannel of a communications channel 
configured to use the HASP ring-0 multiplexer. See the description of the HASP 
multiplexer in MAM Communications. 

This I/O module is designed primarily for use by the Multics I/O daemon. 
ATTACH DESCRIPTION 

hasp_host_ -control_args 
CONTROL ARGUMENTS 

The following control arguments are optional, with the exception of -comm, -device, 
and -tty: 

-comm hasp 

is required for compatibility with other I/O modules used by the I/O daemon, 
-ebcdic 

is accepted for compatibility with other I/O modules used by the I/O daemon, 
but is ignored by this I/O module. 

-device STR 

specifies the type of device for this attachment STR must be one of teleprinter, 
reader, printer, or punch. The type specified by this control argument must match 
the type of device attached to the channel name defined below. 

-physical_line_length N, -pll N 

is accepted for compatibility with other I/O modules used by the I/O daemon, 
but is ignored by this I/O module. 

-terminal_type STR, -ttp STR 

is optional and is used to define the character set used by the remote system. 

STR must be the name of a terminal type defined in the site's terminal type 
table (TTT). See "Character Set Specification" below. 

-tty channel_name 

specifies the communications channel to be attached. The channel must be a 
subchannel of a HASP multiplexed channel (e.g., a.h014.prt3). 

OPEN OPERATION 

The hasp_host_ I/O module supports the sequential_input, sequential_output, and 
sequential_input_output opening modes. 

WRITE RECORD OPERATION 

The write_record operation converts the supplied data record from ASCII to the 
remote system's character set, performs data compression, and transmits the record to 
the HASP multiplexer. 
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The format of the record supplied to this I/O module follows. This structure and the 
referenced constants are contained in the terminal_io_record.incl.pll include file: 



al igned based, 
fixed binary, 
fixed binary, 



fixed binary 
fixed binary 



(18) 
(18) 



del 1 termi nal_io_record 
2 version 
2 device__type 
2 slew_control , 

3 slew_type 

3 slew_count 
2 flags, 

3 binary 

3 preslew 

3 pad 
2 element_size 
2 n_elements 
2 data, 

3 bits (termi nal_io_record_n_elements refer 
(termi nal_i o_record .n_elements) ) 
bit (termi na l_i o_record_el ement_s i ze refer 
(terminal_io_record.element_size) ) una! igned; 



unaligned unsigned, 
unaligned unsigned, 



bit (1) unal i gned, 
bit (1) unal igned, 
bi t (3*0 unal igned, 
fixed binary, 
f i xed bi nary (2*+) , 



STRUCTURE ELEMENTS 



version 

is the current version of this structure given by the value of the named constant 
terminal_io_record_version_l. (Input) 

device_type 

is the type of device to which this record is to be written. (Input) The 
acceptable values are TELEPRINTER_DEVICE and READER_DEVICE. 

slew_control 

is ignored by this I/O module, as the HASP communications protocol does not 
define slew operations for either the teleprinter or card reader. (Input) 

flags.binary 

must be set to "0"b. (Input) (This I/O module does not support binary data 
transmission.) 

flags, preslew 

must be set to "0"b. (Input) 

element_size 

must be set to 9. (Input) (This I/O module only supports transmission of 
characters.) 

n_elements 

is the number of characters in the record to be written. (Input) 
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data.bits 

is the actual data. (Input) This I/O module expects to be supplied ASCII 
characters. 



READ RECORD OPERATION 



The read_record operation returns a single record from the device, basically 
performing the inverse of the functions described for the write_record operation. 
Additionally, for line printer attachments, the carriage control information in the 
record is converted into the appropriate slew information in the terminal_io_record 
structure. 



The format of the record that this I/O module returns in the supplied buffer is as 
follows. The structure and the referenced constants are contained in the 
terminal_io_record. incl. pi linclude f ile: 



del 1 termi nal_io_record 
2 version 
2 device_type 
2 s 1 ew_control , 

3 slew_type 

3 slew_count 
2 flags, 

3 binary 

3 preslew 

3 pad 
2 el ement_s i ze 
2 n_e 1 ements 
2 data, 

3 bits (termi nal_io_record_n_el ements refer 
(termi na l_i o_record . n_el ements) ) 
bit (termi na l_i o_record_el ement_s i ze refer 
(terminal_io_record.element_size) ) unal igned; 



al i gned based, 
fixed binary, 
fixed binary, 

fixed binary (18) unaligned unsigned, 
fixed binary (1 8) una 1 i gned unsigned, 

bit (1) unal i gned, 
bit (1) unal i gned, 
b i t (3^) una 1 i gned , 
fixed binary, 
f i xed b i nary {2k) , 



STRUCTURE ELEMENTS 



version 

is the current version of this structure given by the value of the named constant 
terminal_io_record_version_l. (Output) 

device_type 

is the type of device from which this record is to be read. (Output) Its possible 
values are TELEPRINTER_DEVICE, PRINTER_DEVICE, or PUNCH_DEVICE. 

slew_control 

if the input device is a line printer, it is filled in with the interpretation of the 
HASP carriage control record present in each line printer record: otherwise, it is 
always set to the value specified below. (Output) 
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slew_type 

for a line printer, is set to the type of slew operation to be performed before or 
after "printing" the data in the record and can be either SLEW_BY_COUNT or 
SLEW_TO_CHANNEL. (Output) For a teleprinter or punch, it is set to 
SLEW_BY_COUNT. (The data returned is processed by the caller of this I/O 
module; this processing is herein termed the "printing" of the data.) 

slew_count 

for a line printer, is set to the value to be interpreted according to 
slew_control.slew_type above. (Output) For a teleprinter or punch it is set to 1. 
(Output) 

flags, binary 

is always set to "0"b. (Output) 

flags, preslew 

for a line printer, is set to "l"b if the slew operation above is to be performed 
before "printing" the data in the record, or is set to "0"b if the slew operation is 
to be performed after "printing". (Output) For other than the line printer, it is 

alwayc SCt tO "Q"b. 

element_size 

is always set to 9. (Output) 

n_elements 

is set to the number of characters returned in the record. (Output) 
data, bits 

is the actual returned data. (Output) This I/O module converts the data input 
from the remote host to ASCII. 

CONTROL OPERATION 

This I/O module supports the following control operations: 
end_write_mode 

ensures that all previously written data has been transmitted to the HASP 
multiplexer and then writes an end-of-file record for the device. 

hangup_proc 

is used to specify a procedure to be invoiced when this attachment's channel is 
hung up. The info_ptr points to the following structure: 

del 1 hangup_proc_i nf o aligned, 

2 procedure entry variable, 

2 data_ptr pointer, 

2 priority fixed binary; 
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where: 
procedure 

is the procedure to be invoked when the hangup occurs. (Input) 
data_ptr 

is a pointer to be supplied to the procedure. (Input) 
priority 

is the priority for the hangup event. (Input) 

See the ipc_ subroutine for a detailed explanation of data_ptr and priority. 
read_status 

determines whether or not there are any records waiting for a process to read. 
The info_ptr should point to the following structure, which is filled in by the 
call: 

del 1 i nf o_structure aligned, 

2 ev_chan fixed bin (71). 
2 i nput_avai 1 abl e bit (1); 

where: 
ev_chan 

is the event channel used to signal the arrival of input. (Output) 

input_available 

indicates whether input is available (Output): 
"0"b no input 
"l"b input 

resetread 

discards any pending input. 

resetwrite 

discards any as-yet unprocessed output 
runout 

ensures that all data has been transmitted to the HASP multiplexer from where it 
is guaranteed to be transmitted to the terminal. 

select_device and reset 

are ignored rather than rejected for compatibility with other I/O modules used by 
the I/O daemon. 

signon_record 
no_signon_record 

can only be issued on the operator's console subchannel of the multiplexer. These 
are described in the "SIGNON Processing" section. 
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MODES OPERATION 



This module accepts the non_edited and default modes for compatibility with other 
I/O modules used by the I/O daemon, but ignores them. 



CHARACTER SET SPECIFICATION 



This I/O module allows the specification of the character set used by the remote 
system through the -terminal_type attach option. 

If -terminal_type is given, the referenced terminal type must be defined in the site's 
(TTT) with an input and an output translation table. This module uses these 
translation tables to convert data from the remote system's character set to ASCII and 
vice versa. 

If -terminal_type is not given, the remote system is assumed to use EBCDIC. In this 
case, the ascii_to_ebcdic_ subroutine is used to convert data sent to the system; the 
ebcdic_to_ascii_ subroutine is used to convert data received from the remote system. 



SICNQN PROCESS! NC 



Before communicating with certain remote systems, Multics must send the SIGNON 
record. This specially formatted record identifies Multics to the remote system. 

For these systems, the Multics multiplexer must be configured to use signon_mode (see 
MAM Communications). Before data transmission is permitted, the signon_record 
control order must be issued on an I/O switch attached to the operator's console 
subchannel of the multiplexer. 

If the remote system does not expect a SIGNON record, the no_signon_record control 
order can be used to validate that the multiplexer channel is properly configured. 

SIGNON _RECORD CONTROL ORDER 

This control order supplies a SIGNON record for transmission to the remote system. 
The info_ptr must locate the following structure, which is declared in the include file 
hasp_signon_record_inf o.incl.pll: 

del 1 s i gnon_record_i nf o aligned based, 

2 version fixed binary, 

2 pad bit (36) , 

2 event_channel fixed binary (71), 

2 record character (80) unaligned; 
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STRUCTURE ELEMENTS 
version 

is the current version of this structure. It must have the value of the named 
constant SIGNON_RECORD_INFO_VER3ION_l. 

pad 

is reserved for future expansion and must be zero. 
event_channel 

is an event-wait channel whose use is described below, 
record 

is the actual text of the SIGNON record in ASCII. This I/O module translates 
the text to uppercase and the remote system's character set 

If the status code returned by this control order is zero, the calling program must 

block on the above event-wait channel. When the wakeup arrives, the event message 

indicates the success or failure of the control order. It has one of the following 

values (found in the named include file): 

HASP_SIGNON_OK 

indicates that the remote system has accepted the SIGNON record. 

HASP_SIGNON_REJECTED 

indicates that the remote system has rejected the record; the caller should try 
again with a different record. 

HASP_SIGNON_HANGUP 

indicates that the remote system has rejected the record and disconnected the 
multiplexer. 

If the status code returned by the control order is error_table_$invalid_state, the 
multiplexer is not configured to send a SIGNON record. 

NO_SIGNON_RECORD CONTROL ORDER 

This control order validates that the multiplexer is not configured to send a SIGNON 
record to the remote system. This order does not accept an info structure. 

If the returned status code is error_table_$invalid_state, the multiplexer is configured 
to send a SIGNON record, and a signon_record must be issued on this subchannel. 

NOTES 

As stated above, this I/O module is used to simulate the operation of a single device 
of a HASP workstation. 



3-43 



AG93-05 



hasp_host_ hasp_workstation_ 



If the simulated device is a card reader, the caller supplies records to this module 
that are then formatted and transmitted to the remote host; in other words, a card 
reader attachment through this switch is an output-only attachment. 

Similarly, this I/O module receives records from the remote host when the simulated 
device is either a line printer or a card punch. Thus, line printers and card punches 
attached through this I/O module are input-only devices. 

Special I/O daemon software is provided to allow Multics to simulate the operations 
of a workstation in order to submit jobs to remote systems and receive those jobs' 
output print and punch files. This workstation simulator uses this I/O module for 
communications with the remote host 



Name: hasp workstation_ 

The hasp_workstation_ I/O module performs record-oriented I/O to a single device 
of a remote terminal that supports the HASP communications protocol. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

This module must be attached to a subchannel of a communications channel configured 
to use the HASP ring 0 multiplexer. (See the description of the HASP multiplexer in 
MAM Communications.) 

The module is designed primarily for use by the Multics I/O daemon. It expects 
output for the operator's console and line printers to have been properly formatted by 
the prt_conv_ module. 

ATTACH DESCRIPTION 

hasp_workstation_ -control_args 

CONTROL ARGUMENTS 

The following control arguments are optional, with the exception of -comm, -device, 
and -tty: 

-comm hasp 

is required for compatibility with other I/O modules used by the I/O daemon, 
-device STR 

specifies the type of device for this attachment. STR must be one of 
"teleprinter", "reader", "printer", or "punch". The type specified by this control 
argument must match the type of device attached to the channel name defined 
below 
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-ebcdic 

is accepted for compatibility with other I/O modules used by the I/O daemon, 
but is ignored by this I/O module. 

-forms STR 

specifies the type of forms to be used to print output directed through this 
attachment. STR is an arbitrary string of at most 32 characters whose 
interpretation is site dependent. This control argument is only permitted for a 
line printer. (Default is the null string.) 

-inside_page STR 

specifies the sequence of carriage control operations to be used to move to the 
top of the next "inside" page. An "inside" page is the page on which the I/O 
daemon prints head sheets. This control argument is only permitted for a line 
printer. The format of STR is described in "Carriage Control Specifications" 
below. (Default is "cl".) 

-outside^page STR 

specifies the sequence of carriage control operations to be used to move to the 
top of the next "outside" page. An "outside" page is the page on which the I/O 
daemon prints tail sheets. This control argument is only permitted for a line 
printer. The format of STR is described in "Carriage Control Specifications" 
below. (Default is "cl".) 

-physical_line_length N, -pll N 

is accepted for compatibility with other I/O modules used by the I/O daemon, 
but is ignored by this I/O module. 

-terminal_type STR, -Up STR 

is used to define the character set used by the remote terminal. STR must be the 
name of a terminal type defined in the site's Terminal Type Table (TTT). See 
"Character Set Specification" below for more information, including the default 
character set used if this control argument is omitted. 

-top_of„page STR 

specifies the sequence of carriage control operations to be used to move to the 
top of the next page. This control argument is only permitted for a line printer. 
The format of STR is described in "Carriage Control Specifications" below. 
(Default is "cl".) 

-tty channel_name 

specifies the communications channel to be attached. The channel must be a 
subchannel of a HASP multiplexed channel (eg: a.h014.prt3). 

OPEN OPERATION 

The hasp_workstation_ I/O module supports the sequential_input, sequential_output, and 
sequential_input_output opening modes. 
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WRITE RECORD OPERATION 

The write_record entTy converts the supplied data record from ASCII to the remote 
terminal's character set, converts the supplied slew control into the proper carriage 
control sequences for line printer attachments, performs data compression, and 
transmits the record to the HASP multiplexer. 

The format of the record supplied to this I/O module follows. This structure and the 
referenced constants are contained in the include file terminal_io_record.incl.pll 

del 1 termi nal_i o_record aligned based, 

2 version fixed binary, 

2 device_type fixed binary, 

2 s 1 ew_cont.ro 1 , 

3 slew_type fixed binary (18) unaligned unsigned, 

3 slew_count fixed binary (18) unaligned unsigned, 

2 flags, 

3 binary bit (1) unaligned, 

3 preslew bit (1) unaligned, 

3 pad bit (3*0 unaligned, 

2 element_size fixed binary, 

2 n_elements fixed binary (24), 

2 data, 

3 bits (terminal_io_record_n_elements refer 
(termi nal_i o_record .n_el ements) ) 
bit (terminal_io_record_element_size refer 
(terminal_io record .el ement_s i ze) ) unaligned; 



STRUCTURE ELEMENTS 



version 

is the current version of this structure given by the value of the named constant 
terminal_io_record_version_l. (Input) 

device_type 

is the type of device to which this record is to be written. (Input). The 

acceptable values are TELEPRINTER_DEVICE, PRINTER_DEVICE, or 
PUNCH_DEVICE. 



3-46 



AG93-05 



hasp_workstation_ 



hasp_workstation 



slew_control 

specifies the slew operation to be performed after printing the data in the record, 
and need only be supplied by the caller if device_type is PRINTER_DEVICE. 
(Input) 

slew_type 

specifies the type of slew operation. (Input). The possible values are 
SLEW_BY_COUNT, SLEW_TO_TOP_OF_PAGE, SLEW_TO_INSIDE_PAGE, 
SLEW_TO_OUTSIDE_PAGE, or SLEW_TO_CHANNEL. 

slew_count 

is interpreted according to the value of slew_control.slew_type. (Input) 



flags, binary 

must be set to "0"b. (Input) This I/O module does not support binary data 
transmission. 

flags, preslew 

must be set to "0"b. (Input). This I/O module does not support slew operations 
before printing the record's data. 

element_size 

must be set to 9. (Input). This I/O module only supports transmission of 
characters. 

n_elements 

is the number of characters in the record to be written. (Input) 
data.bits 

is the actual data. (Input). This I/O module expects to be supplied ASCII 
characters. 

READ RECORD OPERATION 

The read_record entry returns a single record from the device, basically performing 
the inverse of the functions described for the write_record operation. 
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The format of the record module returned by this I/O module in the supplied buffer 
follows. This structure and the referenced constants are contained in the include file 
terminal_io_record. 

del 1 termi nal_i o_record aligned based, 

2 version fixed binary, 

2 device_type fixed binary, 

2 si ew_cont.ro 1 , 

2 slew_type fixed binary (18) unaligned unsigned, 

3 slew_count fixed binary (18) unaligned unsigned, 

2 flags, 

3 binary bit (1) unaligned, 

3 preslew bit (1) unaligned, 

3 pad bit (3*0 unaligned, 

2 el ement_s i ze fixed binary, 

2 n_elements fixed binary (2k), 

2 data, 

3 bits (termi nal_i o_record_n_el ements refer 
(termi na l_i o_record . n_el ements) ) 
bit (terminal io record element size refer 
(termi na l_i o_record .el ement_s i ze) ) una 1 i gned; 



STRUCTURE ELEMENTS 



version 

is the current version of this structure given by the value of the named constant 
terminal_io_record_version_l. (Output) 

device, type 

is the type of device from which this record is read. (Output). Its possible values 
are TELEPRINTER_DEVICE or READERJDEVICE. 



slew_control.slew_type 

is always set to SLEW_BY_COUNT. (Output) 



slew_control. slew_count 

is always set to 1. (Output) 

flags.binary 

is always set to "0"b. (Output) 

flags.preslew 

is always set to "0"b. (Output) 

element_size 

is always set to 9. (Output) 

n_elements 

is set to the number of characters returned in the record. (Output) 
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data.bits 

is the actual returned data. (Output). This I/O module converts the data input 
from the remote workstation to ASCII. 

CONTROL OPERATIONS 

This I/O module supports the following control operations: 
end_write_mode 

ensures that all previously written data has been transmitted to the HASP 
multiplexer and then writes an end-of-file record for the device. 

hangup_proc 

is used to specify a procedure to be invoked when this attachment's channel is 
hung up. The info_ptr points to the following structure: 

del 1 hangup_proc_i nf o aligned, 

2 procedure entry variable, 

2 data_ptr pointer, 

2 priority fixed binary; 

where: 
procedure 

is the procedure to be invoked when the hangup occurs. (Input) 
data_ptr 

is a pointer to be supplied to the procedure. (Input) 
priority 

is the priority for the hangup event. (Input) 

A detailed explanation of data_ptr and priority can be found in the 
description of the ipc_ subroutine. 

runout 

ensures that all data has been transmitted to the HASP multiplexer from where it 
is guaranteed to be transmitted to the terminal. 

read_status 

determines whether or not there are any records waiting for a process to read. 

The info_ptr should point to the following structure which is filled in by the 
call: 

del 1 i nf o_structure aligned, 

2 ev_chan fixed bin (71). 

2i nput_avai labible bit (1); 
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where: 
ev_chan 

is the event channel used to signal the arrival of input. (Output) 

input_available 

indicates whether input is available (Output): 
"0"b no input 
"l"b input 

resetread 

flushes any pending input. 

resetwrite 

flushes any as-yet unprocessed output. 

select_device and reset 

are ignored rather than rejected for compatibility with other I/O modules used by 
the I/O daemon. 

MODES OPERATION 

This module accepts the "non_edited" and "default" modes for compatibility with other 
I/O modules used by the I/O daemon, but ignores them. 

CHARACTER SET SPECIFICATION 

This I/O module allows the specification of the character set used by the remote 
workstation through the -terminal_type attach option. 

If -terminal_type is given, the referenced terminal type must be defined in the site's 
TTT with both an input and output translation table. This module uses these 
translation tables to convert data from the remote workstation's character set to ASCII 
and vice versa. 

If -terminal_type is not given, the remote system is assumed to use EBCDIC as its 
character set. In this case, the subroutine ascii_to_ebcdic_ is used to convert data sent 
to the workstation; the subroutine ebcdic_to_ascii_ is used to convert data received 
from the remote system. 

CARRIAGE CONTROL SPECIFICATIONS 

Multics I/O daemon software uses three special slew operations: skip to top of the 
next page, skip to top of the next inside page, and skip to the top of the next 
outside page. By default, this I/O module assumes that all of these slew operations 
can be simulated on the remote workstation's line printer by skipping to channel one. 
However, through use of the -top_of_page, -inside_page, and -outside_page control 
arguments, any sequence of carriage motions can be specified to simulate these slew 
operations. 
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The format of this carriage control specification is: 
Tn:Tn:Tn: . . . 

where n is a numeric value and T represents how to interpret that numeric value. T 
can be either c representing skip to channel n, or s representing slew n lines. 

For example, the string: 
c7:s5:cl2 

means skip to channel seven, space five lines, and finally skip to channel 12. 



Name: ibm pc io 

The ibm_pc_io_ I/O module is used to transfer ASCII files between a Multics process 
and a microcomputer that runs the IBM PC-to-Host data transfer protocol. It 
performs 7-bit stream I/O over an asynchronous communications channel using the 
data transfer protocol for the IBM Personal Computer as defined by IBM in their 
Asynchronous Communication Support Manual, Order No. 6024032. 



Entry points in this module are not called directly by users; rather the module is 
accessed through the I/O system, usinng the micro_transfer command. 

ATTACH DESCRIPTION 

ibm_pc_io_ switch 

ARGUMENTS 

switch 

is the name of the target I/O switch. The switch must be open for 
stream_input_output. The I/O module for the target switch must be supported by 
the timed_io_ module. The user is responsible for setting any modes required by 
the protocol. For example, modes for the user_i/o switch would be: 
" A 8bit,breakall, A echoplex,rawi, A crecho, A lf echo, A tabecho,rawo" 

OPEN OPERATION 

The ibm_pc_io_ I/O module supports the stream_input and stream_output opening 
modes. 

CLOSE OPERATION 

When opened for stream_output, the close entry transmits any remaining data in the 
internal buffer before closing the switch. See Buffering below. 
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PUT CHARS OPERATION 

The put_chars entry transmits the data one line at a time in variable length data 
blocks. The end-of-line character is a carriage return. Lines exceeding 250 characters 
are transmitted in multiple blocks. See Notes below. 

GET CHARS OPERATION 

The get_chars entry reads protocol blocks and returns the message text to the caller's 
buffer. For further explanation of the get_chars entry, see the iox_$get_chars entry. 

GET LINE OPERATION 

The get_line entry reads protocol blocks and returns the message text to the caller's 
buffer. Characters are returned until either a carriage return character is placed in the 
buffer or the buffer is filled. 

CONTROL OPERATION 

This operation is not supported. 

MODES OPERATION 

This operation is not supported. 

BUFFERING 

The IBM PC-to-Host protocol uses variable length data packets. Data not ending with 
a carriage return character is stored in an internal buffer by the the ibm_pc_io_ I/O 
module. 

NOTES 

A line is a string of characters terminated by a carriage return character, 015 (octal). 
Only 250 characters can be transmitted in each line. When a line of text contains 
more than 250 characters, it is divided and one or more carriage returns inserted 
before transmission. For example, a call to ibm_pc_io_ to transmit a 260 character 
line would result in two lines being transmitted, one containing the first 249 characters 
plus a carriage return and the second containing the last 11 characters. 

The IBM PC-to-Host data transfer protocol does not check for errors during 
transmission. 



No particular line speed is guaranteed when transferring data between Multics and a 
microcomputer. Line speed is dependent on the microcomputer and the load of the 
FNP and communication system for Multics. Due to the nature of the IBM 
PC-to-Host protocol, files may not be successfully transferred to Multics over 
high-speed lines. The actual limit depends on the site configuration and current load. 
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DEFINITIONS 



CR$ Carriage Return (Hex OD) (Oct 15) 

X0N$ XON Character (Hex 11) (Oct 21) 

X0FF$ XOFF Character (Hex 13) (Oct 23) 

IBG$ Begin Transmission Code (Hex 1C) (Oct 3*0 

ITH$ Terminate Transmission Code (Hex 17) (Oct 27) 



TRANSMISSION MEDIUM LEVEL PROTOCOL 



Asynchronous, 7 data bits. 
Files must be ASCII text files and have no lines longer than 250 characters. 
MESSAGE BLOCK LEVEL PROTOCOL 

The standard transmission portion of a message block is a variable length character 
block, maximum 250 characters, followed by a carriage return. 

FILE LEVEL PROTOCOL 

When writing programs that implement the IBM PC-to-Host protocol, users should 
follow the procedures listed below: 



The Sending Program 

1. The program should loop, reading the communications line and waiting for 
reception of a text line ending with the control characters IBG$ CR$. 

2. When such a line is received, the program should send a text line ending with 
IBG$ CR$. (This line may contain an informative message as well, such as 
"Starting file transmission.") 

3. The program then transmits the file. Each line in the file should be sent as a 
line ending in a Carriage Return (CR$) 
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4. While transmission is taking place, the program should monitor the input from the 
communications line and take the following actions: 

a. If an XOFF$ CR$ is seen, stop transmission of lines. When an XON$ CR$ 
is seen, resume transmission. 

b. If a line ending in ITM$ CR$ is seen, stop all transmission. This line will 
contain as text the reason the receiving microcomputer has requested 
termination. 

c. When all lines in the file have been sent, the program should send a line 
ending in ITM$ CR$. (This line can contain an appropriate message, such as 
"File transmission completed.") 



The Receiving Program 

1. The program should loop, sending out a message ending in IBG$ CR$ every 15 to 
20 seconds. This message may also contain text, such as "Ready to receive file.") 

2. During the loop in Step 1, the communications line must be monitored continually 
for messages from the microcomputer. When a line ending in IBG$ CR$ is 
received, the program moves on to step 3. 

3. Each line received (after the one ending in IBG$ CR$) should be stored as a file 
record. As these lines end with Carriage Returns (CR$), the program might delete 
the CR$ before storing a line. Before storing a line, the program checks it to see 
if it ends in ITM$ CR$. If it does, the program does not store that line, but 
closes the file and stops operation. 

4. The program can stop transmission by the microcomputer by sending a line ending 
with an ITM$ CR$. This line may also contain a message giving the reason for 
the termination. 

5. If the program is receiving lines faster that they can be stored, it can suspend 
transmission by sending a line consisting of an XOFF$ CR$ to the microcomputer. 
When it has caught up with the input, it can start up transmission by sending a 
line consisting of an XON$ CR$ to the microcomputer. 
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Name: ibm tape io 

The ibm_tape_io_ module is an mtape_ Per-Format module that supports I/O to and 
from IBM standard labeled, unlabeled and DOS formated tapes under control of the 
mtape_ I/O module. The mtape_ IBM Per-Format module (referred to as the "IBM 
PFM" in the remainder of this discussion) may be selected explicitly by the use of the 
mtape_ attach description control argument "-volume_type ibm", or implicitly if the 
volume mounted by mtape_ during attachment is recognized by RCP as being a 
standard IBM tape. Tapes are processed by the IBM PFM in accordance with IBM 
documents: GC26-3795-3 (OS/VS Tape Labels), GC33-5374-1 (DOS/VSE Tape Labels), 
and GC26-3783-5 (OS/VS Data Management Guide). All of these documents are 
collectively referred to as "the Standard" in the remainder of this discussion. 

OPENING 

Opening of the IBM PFM is made by the iox_$open_file or the iox_$open entries 
(via the mtape_ open_file or open entries). The iox_$open_file entry provides for a 
character string open description, describing file processing attributes to be processed 
according to the wishes of the caller. The open description arguments accepted by the 
IBM PFM are described below. If opening is made by the iox_$open entry, the file 
processing attributes are formed from the current default values of the IBM PFM's 
open description arguments. The open description arguments have an initial default 
value, which are denoted in their respective descriptions below, or the default values 
may be changed by the user (see "Default Values" in the mtape_ I/O module 
description.). 

The opening modes supported by the IBM PFM are sequential_input and sequential_output. 
If the opening mode specified is sequential_output, then the mtape_ attach description 
must have specified the "-ring" control argument or the general mtape_ control 
operation "ring_in" must have preceded the opening attempt. 

OPEN DESCRIPTION 



CONTROL ARGUMENTS 
-append, -app 

specifies that the requested file is to be appended to the end of the file set as a 
new file. The requested opening mode must be sequential_output or the file 
opening will be aborted. 

-no_append, -napp 

specifies that the requested file is not to be appended to the end of the file set. 
(Default) 
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-block N, -bk N 

specifies the block size in bytes for output operations and is also required for 
input operations for unlabeled or DOS formated tapes. For input operations on 
standard labeled tapes, the block size is obtained from the file header label 
record. Permissible values are from 18 to 99996 bytes for "F", and 1044480 for 
"IT and "FB" formats, and 18 to 32760 bytes for "V", "VB", "VS" and "VBS" 
formats. (Default value is 8192 bytes.) 

-comment STR, -com STR 

specifies a user comment to be displayed on the user_output I/O switch after the 
file has been successfully opened. The comment text (STR) may be from 1 to 80 
characters in length and 1044480 for "U". (Default is no -comment) 

-default_fixed_record N, -dfr N 

specifies the record length to be used for "f" or "fb" formats in the absence of 

a -record specification. The intended purpose of this control argument is to 

supply a -default value for record size without having to include a -record 
specification in the open description. If the user wishes to explicitly specify the 

record length, the -record control argument should be used. Although the 

-defauit_fixed_record control argument may appear in a users open description 

and be processed accordingly, this would not be considered the proper method of 

explicitly supplying the record length. (Default value is 80) 

-default_spanned_record N, -dsr N 

specifies the record length to be used for "vs" or "vbs" formats, in the absence 
of a -record specification. The intended purpose of this control argument is to 
supply a default value for record size without having to include a -record 
specification in the open description. If the user wishes to explicitly specify the 
record length, the -record control argument should be used. Although the 
-default_spanned_record control argument may appear in a users open description 
and be processed accordingly, this would not be considered the proper method of 
explicitly supplying the record length. (Default value is 1044480) 

— ueiauu_vaiiauic_iccuiu i-«t, -Hlvr JN 

specifies the record length to be used for "v" or "vb" formats, in the absence of 
a -record specification. The intended purpose of this control argument is to 
supply a default value for record size without having to include a -record 
specification in the open description. If the user wishes to explicitly specify the 
record length, the -record control argument should be used. Although the 
-default_variable_record control argument may appear in a users open description 
and be processed accordingly, this would not be considered the proper method of 
explicitly specifying the record length. (Default value is 8192) 

-display, -ds 

specifies that the entire open description, after it has been parsed and any 
necessary defaults added, is to be displayed on the user_output I/O switch. 

-no_display, -nds 

specifies that the open description will not be displayed on the user_output I/O 
switch. (Default) 



3-56 



AG93-05 



ibm_tape_io_ ibm_tape_io. 



-dos 

specifies that the file to be processed is in IBM DOS format. IBM DOS files 
contain only 1 header label (the HDR1 label) and do not retain any information 
as to file format, block length and record length. It is therefore necessary to 
specify the -block, -record and -format control arguments (or allow the default 
values for same to be used) even when opening an IBM DOS file for input. 

-no_dos, -ndos 

specifies that the file to be processed is not in IBM DOS format but is in fact 
in IBM standard OS/VS format (Default) 

-expires date, -exp date 

specifies the expiration date of the file to be created, where date must be of a 
form acceptable to the convert_date_to_binary_ subroutine. (Default is no 
-expires) 

-extend, -ext 

specifies extension of an existing file. 

-no_extend, -next 

specifies that the requested file is not to be extended. (Default) 

-force, -fc 

specified that the expiration date of the file being overwritten is to be ignored. 
-no_force, -nfc 

specifies that the expiration date of a file being overwritten is not to be ignored. 
If the expiration date is not in the past, the user is queried for permission to 
overwrite the file. (Default) 

-format F, -fmt F 

specifies the record format of the file to be created. Permissible values are: U, 
F, V, VS, FB, VB, and VBS. (They may be specified in either upper or lower 
case.) (Default value is VB) 

-label_entry entry, -lbe entry 

specifies the entry point of a user subroutine which will be called to process the 
contents of user label records on input and generate the contents of same, for 
subsequent writing by mtape_ on output (See "Calling sequence for user label 
processing routine" below.) (Default is no -label_entry) 

-iast_fiie, -If 

specifies that the file to be processed is the last file of the file set. 
-not_last_file, -nlf 

specifies that the file to be processed may not be the last file of the file set. 
(Default) 
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-mode STR, -md STR 

specifies the encoding mode used to record the file data. Permissible values of 
STR are ascii, ebcdic or binary. (Default value is ebcdic) 

-modify, -mod 

specifies modification of an. existing file while retaining the file attributes as 
recorded in the original files header label records. 

-no_modify, -nmod 

specifies that modification of an existing file is not to be performed. (Default) 

-name STR, -nm STR 

specifies the file identifier of the requested file. STR can be from 1 to 17 
characters. (Default is no -name) 

-next_file, -nf 

specifies the file to be processed as the next (or first) file of the file set. This 
control argument is intended to be used when sequentially processing files. For 
output operations, if -name or -number are not specified, the values of their 
respective fields are fabricated by using the nexi sequential number as the file 
sequence number and forming the file name by concatenating the string "FILE" 
with the alphanumeric representation of the file number, (i.e. "FILE0001"). 
(Default) 

-not_next_file, -nnf 

specifies that the requested file is not the next file. 

-number N, -nb N 

specifies the file sequence number or numerical position within the file set. 
Permissible values range from 1 to 9999. (Default is no -number) 

-record N, -rec N 

specifies the logical record length in bytes. Permissible values range from 18 to 
1044480 (sys_info$max_seg_size * 4) bytes, but the legality of the record size is 
dependent on the record format specified with the "-format" control argument 
and the block size. In general the record size must be <= the block size with 
the exception of "spanned record" formats (i.e. VS or VBS formats) where the 
record size may be the max allowable. (No default value. The default record size 
is determined by the value of the appropriate "-default_<type>_record" specification, 
where <type> can be either fixed, variable or spanned.) 

-replace STR, -rpl STR 

specifies replacement of an existing file, where STR is the file identifier to use in 
the search for the file to be replaced. (Default is no -replace) 
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-system_use 

specifies that when opening for output, certain fields of the HDR2 and EOV2 
label records will be used to record the recording mode ASCII, EBCDIC or 
BINARY), and the volume name of the next volume in the volume sequence list. 
The fields used for these purposes are HDR2 character position 40 for recording 
mode (recorded as an EBCDIC "1", "2", or "3" for ASCII, EBCDIC, or BINARY 
respectively), and EOV2 character positions 41 - 46 for the next volume name. 
The IBM OS/VS Tape Labels specification marks these fields as "reserved for 
future use". It is therefore recommended that the "-system_use" control argument 
not be used in an interchange environment. 

-no_system_use . 

specifies that the HDR2 and EOV2 label record fields mentioned above will not 
be corrupted. (Default) 

CLOSING 

Closing of the IBM PFM is made by the iox_$close_file or the iox_$close entries (via 
the mtape_ close_file or close entries). The iox_$close_file entry provides for a 
character string close description, describing actions to be taken by the Per-Format 
module upon closing the I/O switch. If closing is made by the iox_$close entry, the 
close time actions are formed from the current default values of the IBM PFMs close 
description arguments. The close description arguments have an initial default value, 
which are denoted in their respective descriptions below, or the default values may be 
changed by the user (see "Default Values" in the mtape_ I/O module description.). 

CLOSE DESCRIPTION 



CONTROL ARGUMENTS 

-close_position STR, -cls_pos STR 

specifies where to physically position the tape volume within the file that is being 
closed. The values of STR are case insensitive and may be selected from bof (for 
beginning of file), eof (for end of file), or leave (to leave the tape volume 
positioned where it is. (Default value is leave) 

-comment STR, -com STR 

specifies a user comment to be displayed on the user_output I/O switch, after the 
file has been successfully closed. The comment text (STR) may be from 1 to 80 
characters in length. (Default is no -comment) 

-display, -ds 

specifies that the entire close description, after if has been parsed and any 
necessary defaults added, is to be displayed on the user_output I/O switch. 

-no_display, -nds 

specifies that the close description will not be displayed on the user_output I/O 
switch. (Default) 
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READ RECORD OPERATION 

The IBM PFM supports the iox_$read_record operation when the I/O switch is open 
for sequential_input. In general, format dependent logical records are extracted from 
physical tape blocks and written into the callers buffer area. As each tape block is 
exhausted, the IBM PFM requests the mtape_ I/O module to read in the next tape 
block. This sequence continues until logical End of File is detected by the IBM PFM, 
at which time error_table_$end_of_info is returned to the caller, and no further 
read_record requests will be accepted by mtape_ or the IBM PFM until the current 
file is closed and another file is subsequently opened. If the callers buffer length is 
not long enough to contain the entire logical record, as much data as will fit in the 
specified buffer is returned and error_table_$long_record is returned to the caller. In 
this case, the IBM PFM will position to the next logical record. If in the course of 
reading logical records, an End of Volume condition is detected by the IBM PFM, 
automatic volume switching is initiated, which if successful, will be transparent to the 
caller. 

WRITE RECORD OPERATION 

The IBM PFM supports the iox_$write_record entry when the I/O switch is open for 
sequential_outpuL In general, data of the specified record length is extracted from the 
users buffer, formatted into logical tape records and written into a physical tape block 
buffer. As each tape block buffer is filled, the IBM PFM requests mtape_ to queue 
up the full buffer for writing and return a pointer to the next buffer to fill. This 
sequence continues until either: (1) The I/O switch is closed or (2) an mtape_ 
"volume_status" or volume_set_status" control operation is requested to be processed. 
In both cases, if a partially filled buffer exists, it will be queued up for writing as a 
short block and all unwritten buffers will be requested to be written out to tape. If 
the I/O switch is being closed, the IBM PFM now writes out the End of File trailer 
sequence. If during the course of writing tape blocks the End of Volume condition is 
detected, the IBM PFM immediatly writes out the End of Volume trailer labels and 
requests a volume switch to mount the tape to contain the next file section. After the 
new tape volume has been successfully mounted, the IBM PFM initiates the volume 
label and new file section header labels and then requests that the unwritten buffers 
at the time of the end of volume detection be written out to tape. At this time, the 
write_record operation being processed at the time of the End of Volume detection is 
resumed. 

POSITION OPERATION 

The IBM PFM supports the iox_$position operation when the I/O switch is opened 
for sequential_input All positioning types legal for sequential_input are supported. 
(See the description of iox_$position earlier in this manual.) 
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READ LENGTH OPERATION 

The IBM PFM supports the iox_$read_length operation when the I/O switch is open 
for sequential_input. The readjength operation is implemented by actually reading the 
next logical record to determine its length, while discarding the actual data. After the 
length has been determined, backspace record position operation is executed to position 
to the location prior to the read_length operation. When executing read_length 
operations on spanned formatted records, or if the read_length operation is to 
determine the length of the first record of the next block, actual tape motion (i.e. 
read forward, and backspace block) may be necessary and will occur automatically. If 
a spanned record spans a volume boundary, volume switching is initiated both when 
doing the actual read operation and the backspace. 

CONTROL OPERATION 

The IBM PFM supports all of the general mtape_ control operations described in the 
mtape_ I/O module description. There are no control operations that are specific to 
the IBM PFM. 

CALLING SEQUENCE FOR USER LABEL PROCESSING ROUTINE 

In order to process user defined file labels when the "-label_entry" open description 
argument is used, the entry variable argument to the "-label_entry" control argument 
must conform to the following calling sequence in order to be called properly by 
mtape_ and its Per-Format modules: 

del user_l abel_entry entry (ptr , char (*) , fixed bin, 
fixed bin, fixed bin, fixed bin (35)); 

call user_l abel_entry (iocb_ptr, user_l abel_data, 1 abel_number , 
label_type, f i le_section_number, code); 



WHERE 
iocb_ptr 

is a pointer to the I/O control block through which the mtape_ I/O module 
is attached. A user_label_entry routine may wish to know more information 
about the file for which it is processing user labels. This can be accomplished 
by calling the iox_$control entry with this iocb_ptr and executing the mtape_ 
"file_status" control operation. 

user_label_data 

is the actual contents of the user label record to be processed (INPUT) or 
written (OUTPUT). The length of this field will be 76 characters on input and 
truncated to same on output 



3-61 



AG93-05 



ibm_tape_io_ 



ibm_tape_io. 



Iabel_number 

is the number of the user label record within the file label group. The IBM 
standard allows from 1 to 9 user label records within a file label group (UHL1 
- UHL9, and UTL1 - UTL9). 

label_type 

is the encoded file label group type that the user_label_entry is being called to 
process label records for. Its possible values are as follows: 

1 = Beginning of file (BOF) label group 

2 = End of volume (EOV) label group 

3 = End of file (EOF) label group 

f ile_section_number 

is the section number of the file for which the user_label_entry routine is 
being called to process user labels for. For multivolume files, this would 
essentially be the number of the volume (the first volume on which a file 
resides being number 1) on which this file "section" resides. For single volume 
files, the file_section_number would always be a 1. 

code 

is a standard system error code, When writing user labels, the user_label_entry 
routine should set code to error_table_$end_of_info in order to tell the caller 
that no more user labels are to be written. Otherwise, the user_label_entry is 
called repeatedly to generate user label data until the maximum number of user 
labels have been written. 

SEARCHING FOR A FILE 

Before a file may be either created or read, its physical position within the volume 
set must be located. In the case of file creation, its physical position may be 
non-existent, but to ensure file set integrity all of the files in the file set must be 
searched to ensure its non-existence. To reduce physical tape searching to a minimum, 
the IBM PFM in concert with miape_ maintains a linked list of file set members, 
with adequate information in each element of the linked list to identify the file it 
represents and its physical position within the volume set. At the time of the first 
opening, the above mentioned linked list of file set members does not exist. In this 
case, the volume set is searched sequentially forward until the desired file is found. 
As each file preceding the desired file is identified, a new element is added to the 
linked list of file set members, extracting file identity and format information from 
the file header and trailer labels, and obtaining the physical position of the file 
header from mtape_. On subsequent file openings, this linked list of file set members 
is searched first, and if the desired file is identified as being one of the elements, the 
volume set is positioned to the indicated position of the file header. If the desired 
file is not found in the linked list of file set members, then the volume set is 
searched forward from the position of the last identified file in the linked list, adding 
to the list as it proceeds in an attempt to find the desired file. 
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There are 6 open description control arguments which deal with identifying a file to 
be processed. These are: -append, -last_file, -name, -next_file, -number and -replace. 
From reading their descriptions above, it can be seen that if some of them were used 
together, they would form an inconsistent identity for a file to be found. (e.g. If 
-last_file and -next_file were used together, they may or may not describe the same 
file.) In order to keep the set of file identity arguments consistent for any given file, 
certain rules are applied when the open description is parsed as follows: 

1. Open description arguments are parsed from left to right. 

2. Any default arguments and their associated values are parsed before the users 
open description is parsed. 

3. Control arguments and their associated values on the right take precedence over 
the same control argument and its value that preceded it. (e.g. In an open 
description which included "-name FILEX -name FILEY", the parsed result would 
be "-name FILEY".) 

4. Binary control arguments (e.g. -last_file) all have an associated antonym value (i.e. 
-no_last_file). As each binary control argument is parsed, it takes precedence and 
replaces any opposite control argument that preceded it. (e.g. In an open 
description which included "-last_file -no_last_file" the parsed result would be 
"-no_last_file".) 

5. For each of the 6 file identity open description arguments, there are a certain set 
of control arguments with which it is mutually exclusive with and takes 
precedence over. The chart below illustrates this mutual exclusitivity: 

j -append j - 1 as t_f i 1 e | -name | -next_f 1 1 e | -number j -rep 1 ace j 



•append 
■last_f i le 
■name 

•next_f i 1 e 
•number 
■repl ace 



FILE IDENTIFIERS 

Associated with every file is a name (file identifier) and a number (file sequence 
number). The file identifier must be 17 characters or less. When creating a file, the 
file identifier must be composed of one or more components of one to eight 
characters, with adjacent components separated by a period. The first character of 
each component must be an uppercase letter or national character (@, #, or $) and 
the remaining characters must be uppercase letters, national characters or the digits 0 
to 9. If a file identifier (of an existing file) does not meet the naming conventions 
established for files created on the Multics system, the file must be referenced using 
the -number control argument and a file sequence number. 
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CREATING A FILE 

When a file is created, an entirely new entity is added to the file set. There are two 
modes of creation: append and replace. In append mode, the new file is added to the 
file set immediately following the last (or only) file in the set. The process of 
appending does not alter the previous contents of the file set. In replace mode, the 
new file is added by replacing (overwriting) an existing file. The replacement process 
logically truncates the file set at the point of replacement, destroying all files (if any) 
that follow consecutively from that point. 

The file to be created may be identified explicitly by specifying the file name and /or 
number (with the -name and -number open description control arguments) either 
together or individually. If a -name and -number control arg appear in the same 
open description, they must identify the same file or an error will result. 

The file to be created may be identified implicitly by specifying one of the relative 
position control arguments, -append, -last_file or -next_file in an open description. 

Implicit file replacement is also accomplished if the file to be created is identified as 
already existing. 

If the user wishes to explicitly specify creation by replacement, the particular file to 
be replaced must be identified. Associated with every file is a name (file identifier) 
and a number (file sequence number.) Either is sufficient to uniquely identify a 
particular file in the file set. The -number N and -replace STR control arguments, 
either separately or in conjunction, are used to specify the file to be replaced. If 
used together, they must both identify the same file; otherwise, an error is indicated. 

When the -number N control argument is specified, if N is less than or equal to the 
sequence number of the last file in the file set, the created file replaces the file 
having sequence number N. If N is one greater than the sequence number of the last 
file in the file set, the created file is appended to the file set. If N is any other 
value, an error is indicated. 

The -format F, -record R and -block B control arguments, or their default values, 
are used to specify the internal structure of the file to be created. They are 
collectively known as structure attribute control arguments. 

When the -format F control argument is used, F must be one of the following 
format codes, chosen according to the nature of the data to be recorded. (For a 
detailed description of the various record formats, see "Record Formats" below.) 
fb for fixed-length records. 

Used when every record has the same length, not in excess of 99996 characters 

(not less than 32760). 

vb for variable-length records. 

Used when records are of varying lengths, the longest not in excess of 32752 
characters. 
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vbs for spanned records. 

Used when the record length is fixed and in excess of 32760 characters, or 

variable and in excess of 32752 characters. In either case, the record length 

cannot exceed 1,044,480 characters. (See "DOS Files" below.) 

f for fixed-length records, unblocked. 

v for variable-length records, unblocked. 

vs for spanned records, unblocked. (See "DOS Files" below.) 

NOTE: Because of padding requirements records recorded using vs format may be 
irreversibly modified. (See "Padding" below.) 

Unblocked means that each block contains only one record (f, v) or record segment 
(vs). Because of their relative inefficiency, the use of unblocked formats in general is 
discouraged. Blocked means that each block contains as many records (fb, vb) or 
record segments (vbs) as possible. The actual number of records/ block is either fixed 
(fb), depending upon the block length and record length, or variable (vb, vbs), 
depending upon the block length, record length, and actual records. 

u for undefined records. 

U format records are undefined in format Each block is treated as a single 
record, and a block may contain a maximum of 1044480 characters. 

When the -record control argument is used, the value of R is dependent upon the 
choice of record format. In the following list, amrl is the actual or maximum record 
length. 

F = fb f: R = amrl 
F = vb v: amrl + 4 <= R <= 32756 
F = vbs | vs: amrl <= R <= 1044480 
F = u: R is undefined 

(the -record control argument should not be used.) 

When the -block control argument is used, the value of B is dependent upon the 
value of R. When the block length is not constrained to a particular value, the largest 
possible block length should be used. 

F = fb: B must satisfy mod (B,R) = 0 

F = f: B = R 

F = vb: b >* R + 4 

F=v: B = R + 4 

F = vbs | vs: 20 <= B <= 32760 

F = u: amrl <= B <= 1044480 
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ENCODING MODE 

The IBM PFM makes provision for three data encoding modes: EBCDIC, binary, and 
ASCII. The default data encoding mode is EBCDIC. File labels are always recorded 
using the EBCDIC character set. 

When a file is created, the -mode control argument can be used to explicitly specify 
the encoding mode. 

If STR is the string ascii, the octal values of the characters to be recorded must be 
in the range 000 <= octal_value <= 377; otherwise, an unrecoverable I/O error occurs. 
If STR is the string ebcdic, the octal values of the characters to be recorded must be 
in the range 000 <= octal_value <= 177. (See the ascii_to_ebcdic_ subroutine for the 
specific ASCII to EBCDIC mapping used by the IBM PFM.) If STR is the string 
binary, any 9-bit byte value can be recorded. However, data written on IBM 
equipment with binary mode may not be compatible with Multics, or vice versa. 

Unless the "-system_use" open description control argument is used, the -mode 

argument must be used when subsequently processing an ASCII or binary file, or the 

default mode must be changed accordingly. (If noi used, the Iist_iape_con tents 
command does not supply the specific mode in its report). 

PADDING 

Unlike its predecessor, the tape_ibm_ I/O module, the IBM PFM does not require 
block padding on output to a modulo 4 characters, unless the recording mode selected 
is binary. In this case the IBM PFM automatically pads every block with from 1 to 3 
blanks to satisfy the modulo 4 requirement. 

READING A FILE 

The open description needed to read a file is less complex than the description used 
to create it When a file is created, the structure attributes specified in the open 
description are recorded in the file's header and trailer labels. These labels, which 
precede and follow each file section, also contain the file name, sequence number, 
block count, etc. When a file is subsequently read, all this information is extracted 
from the labels. Therefore, the open description need only identify the file to be 
read; no other control arguments are necessary. Any of the 6 file identification open 
description control arguments (See "Searching For a File" above.) may be used to 
identify the file to be read. 



DOS FILES 

Files created by DOS installations differ from OS files in one major respect — DOS 
does not record HDR2 labels, which contain the structure attributes. It is therefore 
necessary to specify all of the structure attributes whenever a file created by a DOS 
installation is to be processed. 
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It is further necessary to distinguish between OS and DOS files recorded in VBS or 
VS format The segment descriptor word (SDW) of a zero-length DOS spanned record 
has a high-order null record segment bit set, while a zero-length OS spanned record 
does not. (See "V(B)S Format" below, for an explanation of the SDW.) 

The -dos control argument must be used when writing a VBS or VS file destined for 
a DOS installation, or when reading a VBS or VS file written by a DOS installation. 
In the interest of clarity, however, it is recommended that the control argument 
always be specified when DOS files are processed, regardless of record format. 

OUTPUT OPERATIONS ON EXISTING FILES 

There are two output operations that can be performed on an already existing file: 
extension and modification. As their functions are significantly different, they are 
described separately below. They do, however, share a common characteristic. Like the 
replace mode of creation, an output operation on an existing file logically truncates 
the file set at the point of operation, destroying all files (if any) that follow 
consecutively from that point. 

EXTENDING A FILE 

File extension is the process of adding records to a file without in any way altering 
the previous contents of the file. 

Because all the information regarding structure, length, etc. can be obtained from the 
file labels, the open description need only specify that an extend operation is to be 
performed on a particular file. The previous contents of the file remain unchanged; 
new data records are appended at the end of the file. If the file to be extended does 
not exist, an error is indicated. 

The file to be extended is identified by using any of the 6 open description file 
identifying control arguments. (See "Searching For A File" above.) 

Recorded in the labels that bracket every file section is a version number, initially set 
to 0 when the file is created. The version number is used to differentiate between 
data that have been produced by repeated processing operations (such as extension). 
Every time a file is extended, the version number in its trailer labels is incremented 
by 1. When the version number reaches 99, the next increment resets it to 0. 

Any structure attribute open description control arguments specified by the user are 
ignored when extending a file. 

MODIFYING A FILE 

It is occasionally necessary to replace the entire contents of a file, while retaining the 
structure of the file itself (as recorded in the header labels). This process is known as 
modification. 
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Because all necessary information can be obtained from the file labels, the open 
description need only specify that a modify operation is to be performed on a 
particular file. If a file to be modified does not exist, an error is indicated. The 
entire contents of the file are replaced by the new data records. The version number 
in the trailer labels of a modified file is incremented by 1, as described above. 

Any structure attribute open description control arguments specified by the user are 
ignored when modifying a file. The file to be modified is identified as r.bove. 

FILE EXPIRATION 

Associated with every file is a file expiration date, recorded in the file labels. If a 
file consists of more than one file section, the same date is recorded in the labels of 
every section. A file is regarded as expired on a day whose date is later than or 
equal to the expiration date. Only when this condition is satisfied can the file (and 
by implication, the remainder of the file set) be overwritten. Extension, modification, 
generation, and the replace mode of creation are all considered to be overwrite 
operations. 

The expiration date is recorded in Julian form; i.e., yyddd, where yy are the last two 
digits of the year, and ddd is the day of the year expressed as an integer in the 
range 1 <= ddd <= 366. A special case of the Julian date form is the value "00000" 
(always expired). 

The expiration date is set only when a file is created or generated. Unless a specific 
date is provided, the default value "00000" is used. The -expires date control argument 
is used to specify an expiration date, where date must be of a form acceptable to the 
convert_date_to_binary_ subroutine; the date may be quoted and contain embedded 
spaces - Julian form, including "00000", is unacceptable. Because overwriting a file 
logically truncates the file set at the point of overwriting, the expiration date of a file 
must be earlier than or equal to the expiration date of the previous file (if any); 
otherwise, an error is indicated. 

If an attempt is made to overwrite an unexpired file, the user is queried for explicit 
permission. The -force control argument unconditionally grants permission to overwrite 
a file without querying the user, regardless of "unexpired" status. 

RECORD FORMATS 

Files are structured in one of four record formats: F(B), V(B), V(B)S, or U. When a 
file is created, its record format should be chosen in accordance with the nature of 
the data to be recorded. For example, data consisting of 80-character card images is 
most economically recorded in FB format, blocked fixed-length records. Data 
consisting of variable length text lines, such as PL/ 1 source code produced by a text 
editor, is best recorded in VB or VBS format, blocked spanned records, so that blanks 
are not inserted. 
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With the exception of U format, files are either blocked or unblocked, blocked being 
the usual case. Each block of an unblocked file contains just one record, whereas 
each block of a blocked file can contain several records. Blocking can provide a 
significant savings of processing time, because several records are accessed with a single 
physical tape movement. Furthermore, as blocks are separated by distances of blank 
tape, blocking reduces the amount of tape needed to contain a file. 



F(B) Format 

In F format, records are of fixed (and equal) length, and files have an integral 
number (N) of records per block. If the file is unblocked, N equals 1 and the record 
length (R) equals the block length (B). If the file is blocked, N > 1 and B equals (R 
* N) where N is known as the blocking factor. 

For example, if R equals 800 and B equals 800, then the file is unblocked and each 
block contains just one record. 



data | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



block | 800 | | 800 | | 800 | | 800 | | 800 | | 800 ] 



If R equals 800 and B equals 2400, then the file is blocked, the blocking factor is 3, 
and each block contains three records. 



data | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



block | 800 | 800 | 800 | | 800 | 800 | 800 | 



The Standard for F format records permits recording short blocks. A short block is a 
block that contains fewer than N records, when N is greater than 1. Although the 
IBM PFM can read this variant of F format, it writes a short block in only one case. 
The last block of a blocked file can contain fewer than N records if there are no 
more records to be written when the file is closed. Therefore, blocked F format files 
written by the IBM PFM are always in FBS (fixed blocked standard) format. 
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There are two special cases in which a datum is padded out to length R. The first 
case is that of iobl (the number of characters to be written) equals 0: a record of R 
blanks is written. When such a record is subsequently read, it is interpreted as a 
record of R blanks, and NOT as a zero-length record. The second case is that of 
0 < iobl < R: the record is padded on the right with blanks to length R, and the 
padded record written. When such a record is read, the original characters PLUS the 
padding are returned. The case of iobl greater than R is in error. 

VfB) Format 

In V format, records and therefore blocks may vary in length. Each record is 
preceded by a four-character record descriptor word (RDW) that contains the actual 
record length in binary, including the length of the RDW itself. Each block is 
preceded by a four-character block descriptor word (BDW) that contains the actual 
block length in binary, including the length of the BDW itself. 



V format files have an integral number of records per block, N. If the file is 
unblocked, B = R + 4; if blocked, B >= R + 4; For blocked records, the number of 



:4.t. *i 



records per block varies indirectly wuu me size ui ine recorus. 



If R equals 804, B equals 808, and the file is unblocked, records of up to 800 
characters can be written, but each block can contain only one record. 



data 



375 



280 



800 



block 




280 




If R equals 804, B equals 808, and the file is blocked, records of up to 800 characters 
can be written. Each block can contain a maximum of 201 zero-length records (a 
record written as a 4-character RDW containing the binary value 4). 



data 



I 375 | | 



280 



800 



block 



6 


3 




2 






8 


8 
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7 
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8 


280 




0 


0 


800 
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VfBjS Format 

In V(B)S format, a single record is formatted as one or more record segments. A 
record segment contains either a complete record, the initial portion of a record, a 
medial portion of a record, or the final portion of a record. No two segments of the 
same record can be contained in the same block, but a block may contain the 
segments of several different records. The maximum record length is limited only by 
the maximum size of a storage system segment, currently 1,044,480 characters. 

V(B)S format files have an integral number of record segments per block. If the file 
is unblocked, each block contains only one record segment; if blocked, the number of 
record segments per block is variable. In either case, R and B are independent of one 
another. 

Each record segment begins with a four-character segment descriptor word (SDW). 
The four-character SDW contains a record segment length in binary, that includes the 
length of the SDW itself, plus a binary record segment code in binary, that indicates 
if the segment contains a complete record, or an initial, medial, or final portion. In 
the examples below, R equals 1000 and B equals 800. For unblocked files: 



data 



200 



400 



1000 



block 



2 


2 






4 


4 






8 


8 






2 


2 




0 


0 


200 




0 


0 


400 




0 


9 
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1 


1 
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8 
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8 


4 






0 
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6 


2 





For blocked f i les: 



data | 200 | | 
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record 
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400 
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U Format 

U format files contain records that do not conform to either F(B), V(B), or V(B)S 
format. A U format file is always unblocked. The record length is undefined, and 
the block length must equal or exceed the maximum record length. Blocks may vary 
in length. The special case of writing a record of less than 20 characters produces a 
block padded to length 20 with blanks. 



data | 60 | | 127 I I 16 I I ^6 



block | 60 | | 127 | | 20 | | 156 



VOLUME INITIALIZATION 

The Standard requires that all volumes be initialized with VOL! and dummy HDR1 
labels before they are used for output. The IBM PFM provides a semiautomatic 
volume initialization mechanism that performs this operation as an integral part of the 
output function. It should be noted that, as stated above, a newly initialized volume 
contains a dummy HDR1 label, but not a dummy file. If a file is created on a newly 
initialized volume without an explicit specification of the -number control argument, 
the IBM PFM attempts to append it to the file set, resulting in an error. 

CONFORMANCE TO STANDARD 

With two exceptions, the IBM PFM conforms to the Standard: the IBM PFM ignores 
the data set security field in the HDR1 label on input, and records it as 0 on output; 
if the -system_use open description argument is used, characters positions 40 - 46 or 
the HDR2/EOF2/EOV2 labels, are recorded with the file recording mode and the next 
volume name (EOV2 only). (See label Processing below.) 

LABEL PROCESSING 



VOL1 

The label is processed on input and output. The owner-name and address-code-field, 
character positions (CP) 42 to 51, holds a three-character volume authentication 
code, in character positions 42 to 44 and the character string "MULT001" in 
character positions 45 to 51. 

HDR1/EOF1/EOV1 

The labels are processed on input and output. The system-code-field, CP 61 to 
73 ; is recorded as "MULTICS IBM2 ". 
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HDR2/EOF2/EOV2 

The labels are processed on input and output. The 17-character 
job /job-step-identification-field, CP 18 to 34, is recorded as follows: 

"MULTICS /" || Julian creation date || " " 

If the -system_use open description argument is used on output, then the 
"Reserved for future use" field, character positions 40 to 46 is recorded as 
follows. 

CP 40 - data encoding mode (all) 

"1" = ASCII, 9 mode 
"2" = EBCDIC, 9 mode 
"3" = binary 

CP 41 to 46 - volume name of the next volume (EOV2 only). 



HDR3/EOF3/EOV3 - HDR8/EOF8/EOV8 

These labels are not written on output and are ignored on input. 

UHL1/UTL1 - UHL8/UTL8 

These labels are processed on output and input only 
description argument is given. Otherwise, not written 
input. 

UNLABELED TAPES 

The IBM PFM supports basic processing of unlabeled tapes that are structured 
according to the OS Tape Labels document mentioned at the beginning of this 
description. DOS leading tape mark (LTM) unlabeled format tapes cannot be 
processed. 

In order to process unlabeled IBM tapes, the mtape_ attach description must contain 
the "-no_labels" and "-volume_type ibm" control arguments. The following open 
description control arguments do not apply when processing unlabeled tapes and are 
ignored: 

-name -extend 
-replace -modify 
-expires -dos 
-force 

Volume switching is handled somewhat differently for unlabeled tapes. When the IBM 
PFM detects two consecutive tape marks in the course of an input operation, it 
determines whether or not any volumes remain in the volume sequence list. If another 
volume appears in the list, volume switching occurs and processing continues on the 
next volume. If the list is exhausted, the IBM PFM assumes that end of information 
has been reached. Detection of end of tape during an output operation is handled in 
much the same way as it would be for a labeled tape. (See the OS Tape Labels 
document for a complete description of unlabeled volume switching strategy.) 



if the "-label_entry" open 
on output and ignored on 
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The use of unlabeled tapes is strongly discouraged, particularly as an interchange 
medium. Since no format or volume identification information exists on the recorded 
media itself, it would be very difficult for a foreign site to retrieve data off of an 
unlabeled tape without extensive written instructions. Unlabeled tapes should only be 
used in a highly controlled environment. 



Name: ibm2780_ 

The ibm2780_ I/O module performs stream I/O to a remote I/O terminal that has 
the characteristics of an IBM 2780 data transmission terminal. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

This module in turn constructs an attach description for the module specified in the 
-comm control argument, passing the attach information for ascii or ebcdic, tty, 
transparent or non transparent, and all other attach information specified by the caller. 

ATTACH DESCRIPTION 

ibm2780_ -control_args 

CONTROL ARGUMENTS 

The following control arguments are optional, with the exception of -comm and -tty: 
-ascii 

transmits control information and data in ASCII. 
-carriage_ctl STR 

the eight-character string STR, taken two characters at a time, sets the four 
carriage control characters that specify the advance of 0, 1, 2, and 3 lines. The 
default set of characters is ESCM, ESC/, ESCS, and ESCT, where the mnemonic 
ESC means the ASCII escape character. 

-comm STR 

uses the communications I/O module specified by STR. 
-device STR 

specifies that this attachment is associated with the device STR. Currently, it is 
accepted only for compatibility with other I/O modules. 

—ebcdic 

converts control information and data to its EBCDIC representation before 
transmission. This is the default. 
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-horizontai_tab, -htab 

supports tab control on the remote I/O terminal printer. Tabs are set every 10 
spaces. The default is no tab control. 

-multi_record 

transmits multiple records (up to seven) as a block, rather than separately. The 
default is single-record transmission. 

-nontransparent 

uses a nontransparent communication protocol. This is the default. 
-printer_select STR 

the two-character string STR sets the printer select. The default printer select 
string is ESC/. 

-physical_line_length N, -pll N 

sets the maximum character width of the remote I/O terminal printer to N 
characters. The default is 80 characters. This variable is used to set tabs and pad 
records if the transparent option is specified. 

-punch_select STR 

the two-character string STR sets the punch . select. The default punch select 
string is ESC4. 

-slew_ctl STR 

the six-character string STR, taken two characters at a time, sets the slew control 
characters that specify top of form, inside page, and outside page. The default set 
of characters is ESCA, ESCA, and ESCA. 

-terminal_type STR, -Up STR 

STR specifies the terminal type whose conversion, translation, and special tables 
defined in the user or system terminal type table (TTT) are used to convert and 
translate input and output to and from the device. If not specified, no conversion 
or translation is performed. For more information about the allowable conversion 
values see "Notes" below. 

-transparent 

uses a transparent communication protocol. 

-tty STR 

connects the remote I/O station to the communications channel named STR. 
OPEN OPERATION 

The ibm2780_ I/O module supports stream_input, stream_output, and stream_input_output 
opening modes. 
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PUT CHARS OPERATION 

The put_chars entry splits the data to be written into blocks of 80 or 400 characters, 
depending on whether multirecord mode is enabled, and transmits the number of 
characters specified to the specified communications I/O module. The blocks are of 
fixed or variable length, depending on whether transparent mode is enabled or not, 
respectively. 

GET CHARS OPERATION 

The get_chars entry reads characters up to 80 or 400 characters, depending on whether 
multirecord is enabled, and returns the number requested, up to the next record 
separator. 

CONTROL OPERATION 

This I/O module supports all the control operations supported by the communications 
I/O module specified in the attach description. In addition, it supports the following: 

select_device 

selects the subdevice (printer, punch, or teleprinter) to which output is next 
directed. The input structure is of the form: 

del device char (32) based; 
set_bsc_modes 

sets the character mode, either ascii or ebedic, and transparency. The input 
structure is defined as follows: 

del 1 set_bsc_modes aligned, 

2 char_mode bit(l), unaligned, 
2 transparent bit(l) unaligned; 

where: 

char_mode 

is "l"b if ebedic and "0"b if ascii. 

transparent 

is "l"b if transparency is enabled and "0"b if not. 

set_multi_record_mode 

sets the number of records per block. The input structure is of the form: 

del record_number fixed bin based; 
MODES OPERATION 

This module supports the nonedited and default modes, which set and reset the edited 
output conversion, if it has been enabled by the -terminal_type control argument. 
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NOTES 

The only allowable values in the output conversion table are 00 and any values greater 
than 16. All values defined in the description of the tty_ I/O module are allowed for 
input conversion. Input and output translation tables can be up to 256 characters in 
length. 



Name: ibm3270_ 

The ibm3270_ I/O module performs stream I/O to and from an IBM 3270 
Information Display System (or any compatible device) over a binary synchronous 
communications channel. 

NOTE: Do not use this module to communicate with a 3270 device over a multiplexed 
channel. Use the tty_ module in that case. 

This module description assumes a knowledge of the IBM 3270 communications 
protocol as described in the IBM 3270 I nf or mat ion Display System Component 
Description, Order No. GA27-2749-4. 

Entry points in this module are not called directly by the user; rather, the module is 
accessed through the I/O system. 

ATTACH DESCRIPTION 

ibm3270_ device {-control_args} 

ARGUMENTS 

device 

is the name of the communications channel to be used. 
CONTROL ARGUMENTS 
-ascii 

uses the ASCII bisync protocol and character code, 
-async 

specifies that the I/O module is to return to its caller immediately after 
performing a read order (described below under "Control Operation") when input 
is not available, rather than blocking and waiting for a response from the device. 

-ebcdic 

uses the EBCDIC bisync protocol and character code. This is the default. 
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OPEN DESCRIPTION 

This I/O module supports only the stream_input_output opening mode. If the -async 
control argument is specified in the attach description, the open operation may return 
the status code error_table_$request_pending; in this case, the caller should perform an 
event_info order (see "Control Operation") and block on the returned event channel; 
when the process receives a wakeup on this channel, the open operation should be 
retried. 

CONTROL OPERATION 

This I/O module supports all the orders supported by the tty_ I/O module, as well 
as those described below. All orders are supported when the I/O switch is open, 
except for event_info, which is supported when the I/O switch is attached. 

event_info 

returns the name of the event channel over which wakeups are sent when input 
or status is received from the communications channel. The info_ptr must point 
to an aligned fixed binary (71) number, in which the value of the event channel 
is returned. This order should be used if the -async control argument appears in 
the attach description (see "Attach Description" above). 

general_poll 

causes a general poll operation to be initiated at the 3270 controller. Once the 
I/O switch is open, either a general_poll order or a poll order must be issued 
before any input can be received; however, the general_poll order does not have 
to be repeated, as polling is automatically resumed when appropriate by the I/O 
module. The info_ptr is not used. 

get_input_message_size 

is used to obtain the maximum input message size. The info_ptr must point to a 
fixed binary variable in which the maximum message size is returned as a result 
of the call. This size is the one most recently specified by a set_input_message_size 
order. If no set_input_message_size order has been done since the switch was 
attached, a size of 0 is returned. 

poll 

causes a specific poll operation to be performed on a single device connected to 
the controller. The info_ptr must point to a fixed binary number containing the 
identification number of the device to be polled. To ensure that the device is 
polled as soon as possible, this order usually should be preceded by a 
stop_general_poll order. 

read 

causes input or status information from a single device to be returned, if any is 
available. If no status or input is available for any device on the communications 
channel, then the process blocks if the -async control argument is not specified in 
the attach description; if it is specified, a status code of error_table_$request_pending 
is returned. 
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The info_ptr must point to a user-supplied structure of the following form: 

del 1 read_ctl aligned, 

2 version fixed bin, 

2 areap ptr, 

2 read_infop ptr, 

2 max_len fixed bin, 

2 max_fields fixed bin; 

where: 
version 

is the version number of the structure. (Input). It must be 1. 
areap 

is a pointer to an area in which the read_info structure is allocated. (Output) 
read_infop 

is a pointer to the read_info structure. (Output) 
max_len 

is the largest number of characters that can be returned in a single data 
field. (Output) 

max_fields 

is the largest number of data fields that can be returned in the read_info 
structure. (Output) 

A read_info structure is allocated by the I/O module at the address specified 
by read_ctl.read_infop. This structure must be freed by the calling program. 
The read_info structure has the following form: 
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del 1 read_i nf o aligned based (read_ctl e read_infop) . 
2 version fixed bin, 
2 next_read_i nf op ptr, 
2 controller fixed bin, 
2 device fixed bin, 
2 reason, 

3 key fixed bin, 

3 sub_key fixed bin, 

3 code fixed bin(35)» 
2 status, 

3 bits bit (12) unal , 

3 fill bit (24) unal, 
2 cursor_pos i t i on fixed bin, 
2 max_fields fixed bin, 
2 max_len fixed bin, 
2 mod_fields fixed bin, 

2 data (read_ctl .max_f ields refer (read_i nfo.max_f i elds) ) , 
3 f ield_pos i t ion fixed bin, 
3 contents char (read_ct 1 .max_l en 
refer (read_i nf o.max_l en) ) var; 



where: 



version 

is the version number of this structure. The structure described here is 
version 1. 

next_read_infop 

is a pointer to the next read_info structure used by the I/O module. 
(The calling program should not attempt to make use of this item.) 

controller 

is the identification number of the 3270 controller from which the data 
or status has been received. 

device 

is the identification number of the particular device (attached to the 
specified controller) that produced the data or status information. 

reason 

describes the event that caused the structure to be filled in. 
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key 

identifies the nature of the event, which is either an error or status 
condition, or an action on the part of the 3270 operator. It can have 
any of the following values: 

1 an error was detected at the device. A status code describing the 

error is returned in reason.code (see "code" below). 

2 the device reported status. The particular status is described by 

status.bits (see "status" below). 

3 the operator pressed the ENTER key. 

4 the operator pressed one of the program function (PF) keys. The 

particular key is identified by reason.sub_key (see "sub_key" below). 

5 the operator pressed one of the program attention (PA) keys. The 

particular key is identified by reason.sub_key (see "sub_key" below). 

6 the operator pressed the CLEAR key. 

7 the operator inserted a card in the identification card reader. 

8 the operator used the selector pen on an "attention" field. 

9 the operator pressed the TEST REQUEST key. 

sub_key 

is the number of the PF or PA key pressed if reason.key is 4 or 5, 
respectively. 

code 

is a status code describing an error at the device if reason, key is 1. 
status 

contains the device status if reason.key is 2. 
cursor_position 

is the current position of the cursor on the display screen. 
max_fields 

is the number of elements in the data array (below). 
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max_len 

is the length of the longest contents string (below). 
mod_fields 

is the number of elements in the data array (below) that are actually 
filled in in this instance of the structure. 

data 

describes the data fields containing the input. No data fields are 
provided if reason.key is 1, 2, 5, or 6. 

field_position 

is the starting buffer address of the data field. 

contents 

is the contents of the data field. It is always a null string if reason. key 
is 8. 



set_input_message_size 

specifies the length, in characters, of the largest input message that is expected. 
The info_ptr must point to a fixed binary number containing the message size. A 
size of 0 indicates that there is no maximum message size. Use of this order 
when a maximum message size is defined greatly increases the efficiency of the 
channel. 



stop_general_poll 

causes automatic general polling to stop; polling is not resumed until a 
general_poll order is issued. The info_ptr is not used. 

write 

causes commands and data to be sent to the 3270. The info_ptr must point to a 
user-supplied structure of the following form: 
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del 1 wr i te_i nf o aligned, 
2 version fixed bin, 
2 controller fixed bin, 
2 device fixed bin, 
2 from__device fixed bin, 
2 command fixed bin, 
2 wr i te_ctl_char , 
3 bi ts unal , 

k pr i nt_f ormat bit (2) unal, 
h star t_pr i nter bit(l) unal, 
k sound_alarm bit(l) unal, 
k keyboard_restore bit(l) unal, 
*4 reset_mdt bit(l) unal, 
3 copy_bits bit (2) unal, 
3 pad bit (28) unal , 
2 max_fields fixed bin, 
2 max_len fixed bin, 
2 mod_fields fixed bin, 
2 data (max_wr i te_f i e 1 ds 

refer (wr i te_i nf o.max_f i el ds) ) , 
3 orders unal , 

k set_buf fer_addr bit(l), 
h start_f i eld bi t (1) , 
k i nsert_cursor bit(l), 
h program_tab bit(l), 
h repeat_to_addr bit(l), 
h erase_to_addr bit(l), 
3 attr i butes una! , 
h protected bi t (1) , 
h numer i c bi t (1) , 
h display_form b i t (2) , 
k reserved b i t (1) , 
k mdt bit (1) , 
3 padl bi t (12) unal , 
3 f i eld_pos i t i on fixed bin, 
3 contents char (max_wr i te_l en 

refer (wr i te_i nfo.max__l en) ) var; 

where: 
version 

is the version number of the structure. It must be 1. 
controller 

is the identification number of the 3270 controller to which the data is to be 
sent. 

device 

is the identification number of the device on that controller to which the 
data is to be sent. 
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from_device 

is the identification number of the device to be used as the "from" device 
for a copy command. 

command 

is the command to be sent to the device. It can have any of the following 
values: 

1 write 

2 erase/write 

3 copy 

4 erase all unprotected 

5 read modified 

6 read buffer 

write_ctl_char 

contains the low-order 6 bits of the write control character (WCC) to be 

inserted in the data stream. If command (above) is 3 (copy), this field 

contains the low-order 6 bits of the copy control character (CCC), except 

that the keyboard_resiore and resei_mdt bits are replaced by the copy_bits 
(below). 

copy_bits 

contains the two low-order bits of the copy control character if command is 
3. These are the bits that specify what type of data is to be copied. 

max_fields 

is the number of elements in the data array (below). 
max_len 

is the maximum length of any contents string (below). 
mod_fields 

is the number of elements of the data array actually filled in in this instance 
of the structure. 

data 

describes the individual data fields to be sent to the device, 
orders 

identify orders to be inserted in the output stream. 
set_buffer_addr 

indicates a set buffer address (SB A) order. The field_position (below) contains 
the buffer address to be set. 
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start_field 

indicates a start field (SF) order. The attribute character for the field is 
derived from attributes (below). If an SBA order is also indicated, the field 
starting address is contained in field_position (below); otherwise, the current 
device buffer address is used. The contents string, if nonnull, is written 
starting after the attribute character. 

insert_cursor 

indicates an insert cursor (IC) order. If an SBA order is also indicated, the 
cursor is positioned to the address specified in field_position (below); 
otherwise, it is set to the current device buffer address. If contents is 
nonnull, the data is written starting at the new cursor position. 

program_tab 

indicates a program tab (PT) order. If an SBA order is also indicated, the 
tab is inserted at the address specified in field_position (below); otherwise, it 
is inserted at the current device buffer address. If contents is nonnull, the 
data is written at the start of the field following the tab. 

repeat_to_addr 

indicates a repeat to address (RA) order. The starting address is the current 
device buffer address; the ending address is specified in field_position (below). 
Neither an SBA order nor an EUA order can be indicated in the same field. 
The contents string must consist of a single character, which is to be repeated 
up to the address immediately preceding field_position. 

erase_to_addr 

indicates an erase unprotected to address (EUA) order. The starting address is 
the current device buffer address; the ending address is specified in 
field_position (below). Neither an SBA order nor an RA order can be 
indicated in the same field. If contents is nonnull, the data is written starting 
at the address specified in field_position. 

attributes 

contains the low-order six bits of the attribute character to be assigned to a 
field if start_field (above) is "l"b. 

field_position 

is the device buffer address to be set if set_buffer_addr (above) is "l"b, or 
the ending address if repeat_to_addr or erase_to_addr (above) is "l"b. 

contents 

is the data to be written. It may be a null string. 
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Name: ibm3780_ 

The ibm3780_ I/O module performs stream I/O to a remote I/O terminal that has 
the characteristics of an IBM 3780 data transmission terminal. The hardware options 
currently supported are defined by the control arguments described below. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

This module in turn constructs an attach description for the module specified in the 
-comm control argument, passing the attach information for ascii or ebcdic, tty, 
transparent or non transparent, and all other attach information specified by the caller. 

ATTACH DESCRIPTION 

ibm3780_ -control_args 

CONTROL ARGUMENTS 

The following control arguments are optional, with the exception of -comm and -tly: 
-ascii 

transmits control information and data in ASCII. 
-carriage_ctl STR 

the eight-character string STR, taken two characters at a time, sets the four 
carriage control characters that specify the advance of 0, 1, 2, and 3 lines. The 
default set of characters is ESCM, ESC/, ESCS, and ESCT where the mnemonic 
ESC means the ASCII escape character. 

-comm STR 

uses the communications I/O module specified by STR. 
-device STR 

specifies that this attachment is associated with the device STR. 
-ebcdic 

converts control information and data to its EBCDIC representation before 
transmission. This is the default. 

-horizontal_tab, -htab 

supports tab control on the remote I/O terminal printer. Tabs are set every 10 
spaces. The default is no tab control. 

-multi_record 

transmits multiple records, up to six, as a block, rather than separately. The 
default is single-record transmission. 

-nontransparent 

uses a nontransparent communication protocol. This is the default. 
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-physical_iine_iength N, — pll N 

sets the maximum character width of the remote I/O terminal printer to N 
characters. The default is 80 characters (120 if -device specifies printer). This 
variable is used to set tabs and pad records if the transparent option is specified. 

-printer_select STR 

the one-character string STR sets the printer select. The default printer select 
string is DC1. 

-punch_select STR 

the one-character string STR sets the punch select The default punch select 
string is DC2. 

-slew_ctl STR 

the six-character string STR, taken two characters at a time, sets the slew control 
characters that specify top of form, inside page, and outside page. The default set 
of characters is ESCA, ESCA, and ESCA. 

-terminal_type STR, -ttp STR 

STR specifies the terminal type whose conversion, translation, and special tables 
defined in the user or system terminal type table (il l) are used to convert and 
translate input and output to and from the device. If not specified, no conversion 
or translation is performed. For more information about the allowable conversion 
values see "Notes" below. 

-transparent 

uses a transparent communication protocol. 

-tty STR 

connects the remote I/O station to the communications channel named STR. 
OPEN OPERATION 

The ibm3780_ I/O module supports stream_input, stream_output, and stream_input_output 
opening modes. 

PUT CHARS OPERATION 

The put_chars entry splits the data to be written into blocks of 80 or 512 characters, 
depending on whether multirecord mode is enabled, and transmits the number of 
characters specified to the specified communication I/O module. The blocks are of 
fixed or variable length, depending on whether transparent mode is enabled or not, 
respectively. 

GET CHARS OPERATION 

The get_chars entry reads characters up to 80 or 512 characters, depending on whether 
multirecord mode is enabled, and returns the number requested, up to the next record 
separator. 
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CONTROL OPERATION 

This I/O module supports all the control operations supported by the communications 
I/O module specified in the attach description. In addition, it supports the following: 

select_device 

selects the subdevice (either printer, punch, or teleprinter) to which output is next 
directed. The input structure is of the form: 

del device char (32) based; 
set_bsc_modes 

sets the character mode, either ascii or ebedic, and transparency. The input 
structure is defined as follows: 

del 1 set_bsc_modes aligned, 

2 char_mode bit(l), unaligned, 
2 transparent bit(l) unaligned; 

where: 

char_mode 

is "l"b if ebedic and "0"b if ascii. 

transparent 

is *T'b if transparency is enabled and "0"b if not 

set_multi_record_mode 

sets the number of records per block. The input structure is of the form: 

del record_number fixed bin based; 
MODES OPERATION 

This module supports the nonedited and default modes, which set and reset the edited 
output conversion, if it has been enabled by the -terminal_type control argument 

NOTES 

The only allowable values in the output conversion table are 00 and any values greater 
than 16. All values defined in the description of the tty_ I/O module are allowed for 
input conversion. Input and output translation can be up to 256 characters in length. 
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Name: in tape 

The mtape_ I/O module supports physical and logical I/O to or from magnetic tape 
volume(s), in any one of several formats, including: 

ANSI standard format 
IBM standard format 

IBM Disk Operating System (DOS) format 
IBM unlabeled format 

Entries in this module are not called directly by users; rather, the module is accessed 
through the I/O system. See the Multics Programmer's Reference Manual, Order 
No. AG91 for a general description of the I/O system. 

DEFINITION OF TERMS 

For the purpose of this document, the following terms have the meanings indicated, 
block 

a collection of characters written to or read from a tape volume as a unit. A 
block may contain one or more complete records, or it may contain parts of one 
or more records. A part of a record is a record segment. A block does not 
contain multiple segments of the same record. 

file 

a collection of information consisting of blocks pertaining to a single subject A 
file may be recorded on all or part of a volume, or on more than one volume. 

file set 

a collection of one or more related files, recorded consecutively on a volume set. 
per- format module 

an externally callable subroutine with several standard entry points. The naming 
convention for per-format modules is in the form of <volume_type>_tape_io_ 
where <volume_type> is the character string description of the volume label type 
as returned by RCP on tape input or requested by the user by the use of the 
-volume_type attach description argument or the default volume type on tape 
output For a discussion of the definition and use of per-format modules, see 
"Per-format Modules" below. 

record 

related information treated as a unit of information. A record is the smallest unit 
of information which can be written to tape. 

volume 

a reel of magnetic tape. A volume may contain one or more complete files, or it 
may contain sections of one or more files. A volume does not contain multiple 
sections of the same file. 
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volume set 

a collection of one or more volumes on which one and only one file set is 
recorded. Volume sets may have any of the following relationships to a file set. 

single-volume file 

a single file residing on a single volume 

multivolume file 

a single file residing on multiple volumes 

multifile volume 

multiple files residing on a single volume 

multifile multivolume 

multiple files residing on multiple volumes 

ATTACH DESCRIPTION 

In addition to the I/O module name, only information relevant to the entire volume 
or volume set is supplied in the attach description. For the specification of 
information pertaining to files and file sets, refer to the section titled "Open 
Description" below. The attach description is a contiguous character string and has the 
following form: 

mtape_ vnl {-comment vnl_str} vn2 {-comment vn2_str} 

vnN {-comment vnN_str} {-control_args} 



ARGUMENTS 
vni 

is a volume specification. In the simplest (and typical) case, a volume 
specification is a volume name. Occasionally, keywords must be used with the 
volume name. For a discussion of volume names and keywords see "Volume 
Specification" below. 

-comment vni_str, -com vni_str 

allows the optional specification of a message to be displayed on the operators 
console at the time volume vni is to be mounted. The comment text, vni_str, 
may be from 1 to 64 characters in length and must be quoted if it contains 
embedded white space. 
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vnl vn2 ... vnN 

comprise the volume sequence list It can specify all volumes of the voluem set, 
followed by other volumes to be added to the volume set as new files are 
written. The entire volume set membership need not be specified in the attach 
description; however, the first (or only) volume set member must be specified, 
because its volume name is used to identify the file set. If the current volume 
sequence list becomes exhausted during volume switching, 

the user is queried for the next volume name when new volumes are needed. 
For more information, see "Volume Switch" below. 

CONTROL ARGUMENTS 

is a sequence of one or more attach control arguments. A control argument may 
appear only once. 

-default_volume_type STR, -dvt STR 

specifies the volume type (STR) to be used for Per-Format module selection when 
an unreadable or unlabeled tape is mounted for potential output operations and no 
-volume_type control argument is given. Permissable values for this control 
argument are ansi, or ibm. (Default value is ansi.) 

-density N, -den N 

specifies the recording density for output operations in bits per inch (BPI). For 
input operations, the density is determined and set automatically by RCP. 
Permissible values are 200, 556, 800, 1600 and 6250. (Default density is 1600 BPI.) 

-device N, -dv N 

specifies the number of tape devices that will be requested to be used 
simultaneously for multivolume operations. Permissible values are from 1 to 63. 
(Default is 1 device.) 

-display, -ds 

specifies that the entire attach description, after it has been parsed and any 
necessary defaults added, will be displayed on the user_output I/O switch. 

-no_display, -nds 

specifies that the attach description will not be displayed. (Default) 

-error, -err 

specifies that verbose error messages will be displayed when exception conditions 
(e.g. unrecoverable tape errors) are detected. (Default) 

-no_error, -nerr 

specifies that only error codes will be returned upon detection of exception 
conditions. 

-label, -lbl 

specifies that volume and file label records exist and or are to be recorded by 
the selected Per-Format module. (Default) 
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-no_Iabel, -no_Iabe!s, -nlbl 

specifies that volume and file label records do not exist or are not to be 
recorded by the selected Per-Format module. If this control argument is given 
when attempting to select a Per-Format module that does not accept unlabeled 
tape volumes, the attachment is aborted. 

-ring, -rg 

specifies that volumes are to be mounted with write rings installed. 
-no_ring, -nrg 

specifies that volumes are to be mounted with no write rings installed. (Default) 

-speed Nl {,N2 Nn} , -ips Nl {,N2 Nn] } 

specifies desired tape drive speed(s) in inches per second (IPS), permissible values 
are 75, 125 and 200. If more than one speed device is to be used, the optional 
second and third speed specification must be separated by commas as shown. If 
this control argument is omitted, RCP will pick any available speed device. 

-system, -sys 

specifies that the user is requesting to be considered a system process. 
-no_system, -nsys 

specifies that the user is not to be considered a system process. (Default) 
-track N, -tk N 

specifies the track type of the tape drive to be used. Permissible values are 7 or 
9. (Default is 9 track.) 

-volume vni, -vol vni 

specifies that the following volume name (vni) begins with a hyphen (-) and 
would otherwise be considered a control argument 

-volume_type STR, -vt STR 

specifies the volume type to be used in Per-Format module selection. Permissable 
values for this control argument are ansi, or ibm. (No Default. The volume type 
is determined by RCP for labeled volumes and by the -default_volume_type 
specification for unlabeled or unreadable volumes.) 

-wait, -wt 

specifies that when tape devices are not immediately available from RCP for a 
requested volume mount, the mtape_ I/O module should wait for the number of 
minutes specified by the -wait_time control argument (or its default value), before 
reporting an error on the initial volume mount or subsequent volume switching. 
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-no_wait, -nwt 

specifies that the mtape_ I/O module will not wait for an available device to 
become free, but instead report an error immediately. (Default) 

-wait_time N, -wtm N 

specifies the time (in minutes) that the mtape_ I/O module will wait for 
unavailable tape drives to become available for volume mounts when the -wait 
control argument is specified. Permissible values range from 1 to 1440 minutes (24 
hours). (Default wait time is 10 minutes.) 

VOLUME SPECIFICATION 

The volume name (also called the slot identifier) is an identifier physically written on, 
or affixed to, the volume's reel or container. 



If a volume name begins with a hyphen (-), the -volume keyword must precede the 
volume name. Even if the volume name does not begin with a hyphen, it may still be 
preceded by the keyword. The volume specification has the following form: 

-volume vni 

If the user attempts to specify a volume name beginning with a hyphen without 
specifying the -volume keyword, an error is indicated or the volume name may be 
interpreted as a control argument 

VOLUME SWITCHING 

Volume switching is defined to be the act of switching from the current volume being 
processed, upon detection of physical end of volume, to another volume to continue 
processing. When writing tape, physical end of volume is detected when the end of 
tape reflective foil is passed across the appropriate tape drive sensor. This generates 
an exception status which mtape_ translates to the error_table_$end_of_volume error 
code. This error code is returned to the current Per-Format module upon completion 
of the write operation. The Per-Format module must now write the end of volume 
trailer sequence on the tape. This could consist of writing an end of file mark 
followed by a varying number of end of volume label records followed by 2 
consecutive end of file marks for labeled formats, or simply 2 consecutive end of file 
marks for unlabeled formats. The Per-Format module finds the name of the next 
volume by searching for the next entry in the volume sequence list in the attach 
description. If the volume sequence list is exhausted, the user is queried for the next 
volume name. The Per-Format module must now initiate volume switching, which is 
performed by a common mtape_ entry. 
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Note that when end of volume was detected, the I/O was terminated after successfully 
writing the block when the end of volume condition was first recognized. Due to the 
asynchronous write-behind feature of mtape_, there may have been buffers that were 
not yet written. Part of the contract of the mtape_ volume switch entry is to 
preserve these unwritten buffers and copy their contents from the buffer area of the 
old volume to the buffer area of the new volume. After the new volume has been 
mounted (or re-activated, if it was already mounted), and appropriate validity checks 
done on the new volume, the Per-Format module now writes the volume labels and 
new file section header labels. (If dealing with unlabeled media, this step is omitted.) 
The Per-Format module now must request any saved and unwritten buffers to be 
written out by mtape_. The Per-Format module then resumes writing data to the new 
tape volume. 

When reading tape, the physical end of volume is detected by the Per-Format module 
upon recognition of the end of volume trailer sequence. Volume switching is 
performed as described above, with the exception that there are no unprocessed 
buffers to contend with. In some formats, the name of the next volume is recorded 
in one of the end of volume label records. If this is the case, the Per-Format 
module will force a volume switch to the recorded volume name, even if it is 
different from the next volume name in the volume sequence list. 



The mtape_ I/O module builds and maintains a linked list of file attribute structures 
as each file is processed or recognized in the course of searching for other files. 
Among other things, the file attribute structure contains information as to the file 
identifier, file sequence number and indices of the starting and ending volume set 
member which contain this file. In the course of opening a file, a search of this 
linked list of file attribute structures is made to determine if the requested file has 
already been processed or otherwise recognized during this attachment. If an entry for 
the requested file is found, then the volume set member on which the file resides is 
compared to the volume currently mounted. If this match is made then the physical 
file position on the volume is determined (from information contained in the file 
attribute structure) and the current volume is positioned to the beginning of the 
requested file. If an entry for the requested file is found in the linked list of file 
attribute structures, but the starting volume set member that contains this file is 
different from the current volume, then volume switching is initiated as described 
above. If no entry for the requested file is found in the linked list of file attribute 
structures, then a physical search for the requested file is initiated, starting from the 
current position of the current volume forward through each file position performing 
volume switching as above when necessary. As each file is identified, even though it 
is not the requested file, a file attribute structure is built for it and linked into the 
chain of other file attribute structures. 

RESOURCE DISPOSITION 

The mtape_ I/O module utilizes two types of resources: devices (tape drives) and 
volumes. Once an I/O switch is attached, resources are assigned to the user's process 
on a demand basis. When the I/O switch is detached, the default resource disposition 
unassigns all devices and volumes. 
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VJRITE RINGS AND WRITE PROTECT/ON 

Before a volume can be written on, a write ring (an actual plastic ring) must be 
manually inserted into the reel. This can only be done before the volume is mounted 
on a device. When a volume is needed, the I/O module sends the operator a mount 
message that specifies if the volume is to be mounted with or without a ring. 



In general, the decision of whether write rings are to be installed or not is made at 
attach time. This decision is effected by either the explicit use of the "-ring" attach 
description argument, or the current default value .of the ring specification (See 
"Default Values" below). If output operations are to be performed on the volume set, 
then use installation of write rings must be specified or an error will result when 
attempting to open a file for output The write ring decision may be effected after 
the attach is complete by the use of the "ring_in" control operation described below. 

ERROR PROCESSING AND RECOVERY 

All error recovery of data type errors is initiated by the physical tape interface 
module, tape_ioi_. During read operations, the error recovery procedures used consists 
of initiating the I/O for each block read with automatic hardware retry. If an error 
persists after automatic retry has been performed, then a total of up to 8 retry 
operations are attempted, each time varying the hardware read threshold and deskew in 
different combinations until the block has been read without error, if a data error 
ocurrs while writing a block, tape_ioi_ initiates error recovery procedures which consist 
of backspacing across the block in error, erasing and then re-writing the block for a 
total of up to 8 times until the block has been written successfully. If either a read 
or a write error cannot be recovered in this manner, mtape_ and the user are 
informed that an unrecoverable error exists. mtape_ locks the file and allows no 
further I/O 

until the file is closed and subsequently re-opened. 
OPENING 

Opening is made through the iox_$open_file entry which supports a character string 
"open description" argument for supplying file specific attributes to the per-format 
modules (See "Open Description" below). The iox_$open entry is supported in the 
sense that it will forward the call to the mtape_$open_file entry, supplying a default 
open description. This default open description is different for each per-format 
module. Refer to the section titled "Per-format Modules" below, for details. 

The ANSI and IBM Per-format Modules have a record oriented interface and support 
the sequential_input and sequential_output opening modes only. 

An I/O switch can be opened and closed any number of times in the course of a 
single attachment. All openings are governed by the same attach description. 
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OPEN DESCRIPTION 

The open description is an ASCII character string argument to the iox_$open_file 
entry and provides a means of specifying attributes and position information of the 
desired file to be processed. 

For input operations on one of the supported labeled volume types, a minimal or null 
open description may be specified since all file attributes may be obtained from the 
file header label records or from default values (see "Default Values" below). Only 
file position information (e.g. File number or name) need be specified. If the user 
wishes to process a file set in a sequential manner (i.e. read the first file followed by 
the second file, etc.) and if the mtape_ default open description argument of 
"-next_file" is in force, then a null open description may be used. For output 
operations or input operations for unlabeled volume types, all file attributes and 
positioning information must be specified either in the open description or by using 
their corresponding default values. 

Only those open description specifications that are generic to all of the supported 
volume types are defined below. For open description specifications that are particular 
to a given volume type, see their definition in the section titled "Per Format Modules" 
below. 

In general, the open description consists of zero, one or more control arguments. 

ARGUMENTS 

-append, -app 

specifies that the requested file is to be appended to the end of the file set as a 
new file. The requested opening mode must be sequential_output or the file 
opening will be aborted. 

-no_append, -napp 

specifies that the requested file is not to be appended to the end of the file set. 
(Default) 

-block N, -bk N 

specifies the block size in bytes for output operations and is also required for 
input operations for IBM unlabeled or DOS formatted tapes. For input operations 
on standard labeled IBM or ANSI tape files, the block size is obtained from the 
the file header label record. Permissible values are from 18 to 99996 bytes. 
(Defaults are 2048 bytes for ANSI and 8192 bytes for IBM formats.) 

-comment STR, -com STR 

specifies a user comment to be displayed on the user_output I/O switch, after the 

file has been successfully opened. The comment text (STR) may be from 1 to 80 
characters in length. 
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-def ault_f ixed_record N, -dfr N 

specifies the record length to be used for "f" or "fb" formats in the absence of 
a -record specification. The intended purpose of this control argument is to 
supply a default value for record size without having to include a -record 
specification in the open description. If the user wishes to explicitly specify the 
record length, the -record control argument should be used. Although the 
-default_fixed_record control argument may appear in a users open description 
and be processed accordingly, this would not be considered the proper method of 
explicitly supplying the record length. The default value of N is set to 80 (for 80 
character records) for both the ANSI and IBM PFMs. This default value may be 
changed by the default setting mechanism (see "Default Values" below). 

-default_spanned_record N, -dsr N 

specifies the record length to be used for ANSI "s" or "sb" formats, or IBM "vs" 
or "vbs" formats, in the absence of a -record specification. The intended purpose 
of this control argument is to supply a default value for record size without 
having to include a -record specification in the open description. If the user 
wishes to explicitly specify the record length, the -record control argument should 
be used. Although the -default_spanned_record control argument may appear in a 
users open description and be processed accordingly, this would not be considered 
the proper method of explicitly supplying the record length. The default value of 
N is set to 1044480 (sys_info$max_seg_size * 4) for both the ANSI and IBM 
PFMs. This default value may be changed by the default setting mechanism (see 
"Default Values" below). 

-default_variable_record N, -dvr N 

specifies the record length to be used for ANSI "d" or "db" formats, or IBM V 
or "vb" format in the absence of a -record specification. The intended purpose 
of this control argument is to supply a default value for record size without 
having to include a -record specification in the open description. If the user 
wishes to explicitly specify the record length, the -record control argument should 
be used. Although the -default_variable_record control argument may appear in a 
users open description and be processed accordingly, this would not be considered 
the proper method of explicitly specifying the record length. The default value of 
N is set equal to the default block size (i.e. 2048 for ANSI and 8192 for IBM). 
This default value may be changed by the default setting mechanism (see "Default 
Values" below). 

-display, -ds 

specifies that the entire open description, after it has been parsed and any 
necessary defaults added, is to be displayed on the user_output I/O switch. 

-no_display, -nds 

specifies that the open description will not be displayed on the user_output I/O 
switch. (Default) 

-expires date, -exp date 

specifies the expiration date of the file to be created, where date must be of a 
form acceptable to the convert_date_to_binary_ subroutine. 
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-extend, -ext 

specifies extension of an existing file. 

-no_extend, -next 

specifies that the requested file is not to be extended. (Default) 

-force, -fc 

specifies that the expiration date of the file being overwritten is to be ignored. 
-no_force, -nfc 

specifies that the expiration date of a file being overwritten is not to be ignored. 
If the expiration date is not in the past, the user is queried for permission to 
overwrite the file. (Default) 

-format F, -fmt F 

specifies the record format of the file. Permissible values for ANSI: U, F, D, S, 
FB, DB, and SB; For IBM: U, F, V, VS, FB, VB, and VBS. (They may be 
specified in either upper or lower case.) (Default values are DB for ANSI format 
and VB for IBM formats.) 

-label_entry entry, -lbe entry 

specifies the entry point of a user subroutine which will be called to process the 
contents of user label records on input and generate the contents of same, for 
subsequent writing by mtape_ on output. (See "Calling sequence for user label 
processing routine" described in the ansi_tape_io_ or ibm_tape_io_ description.) 

-last_file, -If 

specifies that the file to be processed is the last file of the file set. 
-not_last_file, -nlf 

specifies that the file to be processed may not be the last file of the file set. 
(Default) 

-mode STR, -md STR 

specifies the encoding mode used to record the file data. Permissible values of 
STR are ascii, ebcdic or binary. (Default for ANSI format is ascii, for IBM 
format the default is ebcdic.) 

-modify, -mod 

specifies modification of an existing file while retaining the file attributes as 
recorded in the original files header label records. 

-no_modify, -nmod 

specifies that modification of an existing file is not to be performed. (Default) 

-name STR, -nm STR 

specifies the file identifier of the requested file. STR can be from 1 to 17 
characters. 
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-next_file, -nf 

specifies the file to be processed as the next (or first) file of the file set. This 
control argument is intended to be used when sequentially processing files. For 
output operations, if -name or -number are not specified, the values of their 
respective fields are fabricated by using the next sequential number as the file 
sequence number and forming the file name by concatenating the string "FILE" 
with the alphanumeric representation of the file number, (i.e. "FILEOOOl"). 
(Default) 

-not_next_file, -nnf 

specifies that the requested file is not the next file. 

-number N, -nb N 

specifies the file sequence number or numerical position within the file set. 
Permissible values range from 1 to 9999. 

-record N, -rec N 

specifies the logical record length in bytes. Permissible values range from 18 to 
1044480 (sys_info$max_seg_size * 4) bytes, but the validity of the record size is 
dependent on the record format specified with the -format control argument and 
the block size. In general the record size must be <= the block size with the 
exception of "spanned record" formats (i.e. ANSI S or SB formats and IBM VS 
or VBS formats), where the record size may be the max allowable. (No default 
value. The default record size is determined by the value of the appropriate 
"-default_<type>_record" specification, where <type> can be either fixed, variable 
or spanned.) For a discussion of valid combinations of record format, record size 
and block size, refer to "Per-Foremat Modules" below. 

-replace STR, -rpl STR 

specifies replacement of an existing file, where STR is the file identifier to use in 
the search for the file to be replaced. 

CLOSE OPERATION 

The I/O switch must be open. Closing is made through the iox_$close_file entry 
which supports a character string "close description" argument for supplying file 
specific attributes to the per-format modules (See "Close Description" below). The 
iox_$close entry is supported in the sense that it will forward the call to the 
mtape_$close_file entry, supplying a null close description. 

CLOSE DESCRIPTION 

The close description is an ASCII character string argument to the iox_$close_file 
entry and provides a means of specifying actions to be taken when closing the current 
file. 

In general, the close description consists of zero, one or more control arguments. 
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CONTROL ARGUMENTS 

-close_position STR, -cls_pos STR 

specifies where to physically position the tape volume within the bounds of the 
file that is being closed. The values of STR are case insensitive and may be 
selected from "bof" (for beginning of file), "eof" (for end of file) and "leave" to 
leave the tape positioned where it is. (Default close position is "leave".) 

-comment STR, -com STR 

specifies a user comment to be displayed on the user_output I/O switch, after the 
file has been successfully closed. The comment text (STR) may be from 1 to 80 
characters in length. 

-display, -ds 

specifies that the entire close description, after it has been parsed and any 
necessary defaults added, is to be displayed on the user_output I/O switch. 

-no_display, -nds 

specifies that the close description will not be displayed on the user_output I/O 
switch. (Default) 

CONTROL OPERATION 

The mtape_ I/O module supports a variety of control operations. 

file_status, fst f i le_set_status , fsst 

f orce_end_of_vol ume, feov hardware_status , hws 

ring_in, rin 

vol ume_status , vst vol ume_set_status , vsst 

In the descriptions below, info_ptr is the information pointer specified in an 
iox_$control entry point call. 

CONTROL OPERATIONS FROM COMMAND LEVEL 

All control operations supported by this I/O module can be executed from command 
level by using the io_call command. The general format is: 

io_call control switchname operation -control_arg 



ARGUMENTS 
switchname 

is the name of the I/O switch that is attached through the I/O module to an 
ANSI tape file-set 

operation 

is any of the control operations previously described. 
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FSLEJJATUS OPERATION 

This operation returns a structure that contains the current status of the file specified 
in the open description. If the I/O switch has never been opened, no information can 
be returned; this situation is indicated by mtape_fst.file_state = 0. If the switch was 
opened, but is now closed, the current status of the file is its status just prior to 
closing. The returned structure is defined in the include file mtape_file_status.incl.pll. 
If a info_ptr is nonull, it must point to the mtape_fst structure shown below. If the 
info_ptr is given as null, then mtape_ will allocate the structure defined below in a 
temporary area on behalf of the user. 

del 1 mtape_fst aligned based (info_ptr), 

2 version char (8) , 

2 file_type fixed bin, 

2 file_state fixed bin, 

2 error_code fixed bin (35) » 

2 f i le_id char (32) , 

2 file_seq fixed bin, 

2 beg i n_vol_i ndex fixed bin, 

2 end_vol_i ndex fixed bin, 

2 f i 1 e_sect i ons fixed bin, 

2 generation fixed bin, 

2 gen_version fixed bin, 

2 creation char (6) , 

2 expiration char (6), 

2 file_format char (3), 

2 block_len fixed bin, 

2 reclen fixed bin (21), 

2 record i ng_mode char (6), 

2 block_count fixed bin (35) » 

2 read_errors fixed bin (35) » 

2 write_errors fixed bin (35); 



version 

is the current structure version. If info_ptr is nonnull on input, the caller must 
set the version element to fst_version_l. Otherwise mtape_ will set the version 
element in the structure it allocates. 

file_type 

is the encoded file set type as determined by RCP, and could have one of the 
following values. 

k = IBM file set 
5 = ANSI file set 
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file_state 

is the current state of this file and could have one of the following values: 

0 = No information available (I/O switch never opened) 

1 = File not open 

2 = File open 

3 = File open and locked for error 

The "locked for error" state referenced above is defined as an error or 
circumstance that prevents continued processing of this file. For example, parity 
error while reading, reached end of information, no next volume available, etc. 

error_code 

is the error code when mtape_fst.file_state is equal to 3 above, otherwise equal to 
0. 

file.id 

is the file name or identifier as recorded in the appropriate file label record. 
This field will be blank for unlabeled formats. 

file_seq 

is the numerical order of this file within the file set. 
begin_vol_index 

is the numerical index of the first volume set member on which this file resides. 
end_vol_index 

is the numerical index of the last volume set member on which this file resides. 
file_sections 

is a count of the number of volumes on which this file resides, 
generation 

is the generation number of this file for those formats that support several 
"generations" of files. If this is the first generation, or if the format does not 
support several generations, then this field will be equal to 0. 

gen_version 

is the generation version number for those formats that support file generations. 
If this is the first generation, or if the format does not support several 
generations, then this field will be equal to 0. 

creation 

is the Julian creation date of this file in the form " yyddd". 
expiration 

is the expiration creation date of this file in the form " yyddd". If no expiration 
date was specified at file creation time, then the field will contain the string 
"00000". 
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file_format 

is the encoded alphabetic representation of the volume type specific file format 
(e.g. "VBS" for IBM variable spanned block format, "DB" for ANSI variable 
record, blocked format, etc.). 

blockjen 

is the maximum block length of each block within this file, 
reclen 

is the maximum record length of the logical records within this file. 
recording_mode 

is the numeric indication of the recording mode of this file. The following values 
are defined: 

0 = Unknown or unspecified 

1 = ASCI I 

2 = EBCDIC 

3 = Binary 



block_count 

is the number of tape blocks contained in this file. If the file is still open, this 
number represents the number of blocks processed thus far. 

read_errors 

is a count of the number of read errors (recoverable as well as unrecoverable) 
encountered while reading this file. Note that read errors recovered by the 
hardware auto retry are not counted. Only Multics reread operations (with varying 
threshold and deskew settings) are counted. 

write_errors 

is a count of the number of write errors (recoverable as well as unrecoverable) 
encountered while writing this file. 

F I LE _SET _STA TUS OPERATION 

This operation may be used to obtain information about the entire file set as opposed 
to just the current file. If nonnull, the info_ptr should point to temporary segment 
which the mtape_ I/O module will fill with a structure as defined below. If the 
info_ptr is given as null, then mtape_ will allocate the structure for the user in a 
temporary area managed by mtape_. This structure is also defined in the include file 
mtape_file_status.incl.pll. 
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del 1 mtape_fsst aligned based (info_ptr) , 

2 vers ion char (8) , 

2 f i le_set_id char (32) , 

2 file_type fixed bin, 

2 nf i 1 es f i xed b in, 

2 fs_stat (mtape_f sst_nf i les 

refer (mtape_f sst .nf i 1 es) ) , 
3 file_state fixed bin, 
3 error_code fixed bin (35) » 
3 f i le_id char (32) , 
3 file_seq fixed bin, 
3 beg i n_vol_i ndex fixed bin, 
3 end_vol_i ndex fixed bin, 
3 f i 1 e_sect i ons fixed bin, 
3 generation fixed bin, 
3 gen_version fixed bin, 
3 creation char (6), 
3 expiration char (6), 
3 file_format char (3), 
3 block_Jen fixed bin, 
3 reclen fixed bin (21), 
3 record i ng_mode char (6), 
3 block_count fixed bin (35) » 
3 read_errors fixed bin (35) » 
3 write_errors fixed bin (35); 



version 

is the current structure version. If info_ptr is nonnull on input, then the caller 
must set the version field to fsst_version_L If null, mtape_ will set the version 
element in the structure it allocates. 

file_set_id 

is the file set identifier recorded in the file labels. This is usually the volume 
name of the first volume in the volume set. 

file_type 

is the encoded file set type as determined by RCP, and could have one of the 
following values. 

h = I BM file set 
5 « ANSI file set 
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nfiles 

is the number of files in the file set 
fs_stat 

is an array of structures of file set members, which appears below in sequential 
order. If the user allocates this structure, then the variable mtape_fsst_nfiles 
(declared in the mtape_file_status include file) must be set to the maximum 
number of files in the file set. 

file_state through write_errors 

is the status of each file in the file set and are the same as the identical names 
described in the mtape_fst structure for the file_status control operation above. 

FORCE _END_OF VOLUME OPERATION 

This operation forces the end of a volume condition and initiates volume switching 
when writing a file. The I/O switch must be open for output. This operation is 
equivalent to detection of the end of tape reflective strip. The info_ptr should be a 
null pointer. 

HARDWARE _STATUS OPERATION 

This operation returns a structure that contains the raw IOM status and the english 
language description of this status, generated by the last tape I/O operation. The I/O 
switch must be open. The returned structure is shown below and is defined in the 
include file mtape_hardware_status.incl.pll. If info_ptr is nonnull, it must point to the 
mtape_hardware_status structure shown below. If info_ptr is given as null, then 
mtape_ will allocate the return structure in a temporary area on behalf of the user. 

del 1 mtape_hardware_status aligned based (info_ptr), 
2 version char (8) , 
2 description char (256) varying, 
2 pad bit (36) , 
2 iom_status bit (72), 
2 iom_l pw bi t (72) ; 



ARGUMENTS 
version 

is the current structure version. If info_ptr is nonnull on input, then the caller 
must set the version element to hwst_version_l. If null, mtape_will set the 
version number in the structure it allocates. 

description 

is the English language description of this hardware status. 



3-105 



AG93-05 



mtape_ 



mtape_ 



iom_status 

is the raw I/O status words returned from the last I/O operation. A definition 
for the format of these status words can be found in the include file 
iom_status.incl.pll. 

iom_lpw 

is the I/O List Pointer Word as it appeared at the termination of the last I/O 
operation. A definition of the format of the LPW can be found in the include 
file iom_lpw.incl.pll. 

RINGJN OPERATION 

This operation will cause subsequent volume mounts to be requested with write rings 
installed. The I/O switch must be closed and the info_ptr set to null. The effect of 
this operation is to cause the current volume to be demounted and the write ring 
indicator to be set in the internal data base maintained by mtape_. At the time of 
the next file opening, the appropriate volume will be requested to be mounted with a 
write ring installed. If write rings have already been requested to be installed, either 
by the use of the -ring attach description argument, or by a previous invocation of 
the ring_in control operation, then the ring_in control operation is considered a 
"no-op" and has no effect. 

VOLUME_STATUS OPERATION 

This operation returns a structure that contains the status of the current volume. If 
the I/O switch is open, the current volume is the volume on which the file section 
currently being processed resides. If the switch has never been opened, the current 
volume is the first (or only) volume in the volume set If the switch was opened, but 
is now closed, the current volume is that on which the last file section processed 
resides. The returned structure is defined in the include file mtape_volume_status.incl.pll 
as well as below. If info_ptr is nonnull, then it must point to the mtape_vst structure 
shown below. If the info_ptr is given as null, then mtape_ will allocate the structure 
in a temporary area on behalf of the user. 
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del 1 mtape_vst aligned based (i nf o_ptr) , 
2 version char (8) , 
2 volume_type fixed bin, 
2 volume_name char (32) , 
2 voiume_id char (32), 
2 mounted bit (1) , 
2 device_name char (8), 
2 volume_index fixed bin, 
2 mounts fixed bin, 
2 tot_er ror_stats , 
3 read, 

h errors fixed bin (35) » 
h operations fixed bin (35) » 
3 wr i te, 

k errors fixed bin (35) > 
h operations fixed bin (35) » 
3 orders, 

k errors fixed bin (35) » 
k operations fixed bin (35) » 
3 successf ul_retry (7) fixed bin (35) » 
2 rel_error_stats, 
3 read, 

k errors fixed bin (35) > 
k operations fixed bin (35) > 
3 wr i te, 

h errors fixed bin (35) » 
h operations fixed bin (35) » 
3 orders, 

h errors fixed bin (35) » 
h operations fixed bin (35) » 
3 successf ul_retry (7) fixed bin (35); 



ARGUMENTS 
version 

is the current structure version. If info_ptr is nonnull on input, the caller must 
set the version element to vst_version_l. If null, then mtape_ will set the version 
element in the structure it allocates. 

volume_type 

is the encoded volume type as determined by RCP, and could have one of the 
following values. 

h = I BM labeled volume 

5 = ANSI labeled volume 

6 = Unlabeled volume 
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volume_name 

is the name of the current volume as specified in the volume sequence list (i.e. 
attach description). 

volume_id 

is the name of the current volume as recorded in the volume label. For 
unlabeled volumes, this field will be blank. 

mounted 

is a flag indicating the mounted state of the current volume. A "l"b indicates 

that the volume, is mounted, "0"b indicates that the volume is not currently 
mounted. 

device_name 

is the name of the tape device that the current volume is mounted on (e.g. 
"tape_01"). If the volume is currently unmounted, this field will be blank. 

volume_index 

is the numerical order of this volume within the volume set. 
mounts 

is a count the number of times the current volume has been mounted during this 
attachment. 

tot_error_stats 

is a block representing the error statistics for the current volume inclusive of all 
of the mounts during the current attachment The block includes the number of 
errors perportioned with the number of operations for read, write and order (i.e. 
non-data transfer operations, like forward space file), as well as a metering array 
of the number of times that read operations were successfully retried for each of 
the combinations of deskew window and threshold changes. 

rel_error_stats 

is the same as tot_error_stats above except it is the error statistics for the current 
mount only. 

VOLUME_SET_STATUS OPERATION 

This operation may be used to obtain information about the entire volume set as 
opposed to just the current volume. If nonnull, the info_ptr should point to a 
temporary segment which the mtape_ I/O module will fill with a structure as in a 
temporary area defined below. If the info_ptr is given as null, then mtape_ will 
allocate the structure for the user. This structure is also defined in the include file 
mtape_volume_status.incl.pll. 
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del 1 mtape_vsst aligned based (info_ptr), 
2 vers ion char (8) , 
2 volume_type fixed bin, 
2 nvolumes fixed bin, 
2 vs_stat (mtape_vsst_nvol umes 

refer (mtape_vsst. nvolumes) ) , 
3 volume_name char (32), 
3 volume_id char (32), 
3 mounted bit (1) , 
3 device_name char (8) , 
3 vol ume_i ndex fixed bin, 
3 mounts fixed bin, 
3 tot__error_stats, 
k read, 

5 errors fixed bin (35) f 
5 operations fixed bin (35) » 
k wr i te, 

5 errors fixed bin (35) » 
5 operations fixed bin (35) » 
k orders, 

5 errors fixed bin (35) » 
5 operations fixed bin (35) » 
k successf ul_retry (7) fixed bin (35) » 
3 rel_error_stats, 
h read, 

5 errors fixed bin (35) » 
5 operations fixed bin (35) * 
k wr i te, 

5 errors fixed bin (35) » 
5 operations fixed bin (35) » 
k orders, 

5 errors fixed bin (35) » 
5 operations fixed bin (35) » 
k successf u1__retry (7) fixed bin (35); 



ARGUMENTS 
version 

is the current structure version. If info_ptr is nonnull on input, the caller must 
set the version element to vsst_version_l. If null, then mtape_ will set the 
version element in the structure it allocates. 

ARGUMENTS 

is the encoded volume type as determined by RCP, and could have one of the 
following values. 

4 = I BM labeled volume 

5 = ANSI labeled volume 

6 = Unlabeled volume 
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n volumes 

is the number of volumes in the volume set. 
vs_stat 

is an array of structures of volume set members, which appears below in 
sequential order. If the user allocates this structure, then the variable 
mtape_vsst_n volumes (declared in the mtape_volume_status include file) must be 
set to the maximum number of volumes in the volume set. 

volume_name through rel_error_stats 

is the status of each volume in the volume set and are the same as the identical 
names described in the mtape_vst structure for the volume_status control operation 
above. 

DETACH OPERATION 

The I/O switch must be closed. Detachment is made through the iox_$detach entry 
which supports a character string "detach description" argument for supplying 
volume-set specific information for the disposition of the volume-set (See "Detach 
Description" below). The iox_$detach_iocb entry is supported in the sense that it will 
forward the call to the mtape_$detach entry, supplying a null detach description. 

DETACH DESCRIPTION 

The detach description is an ASCII character string argument to the iox_$detach entry 
and provides a means of specifying actions to be taken when detaching the current 
volume set. 

In general, the detach description consists of zero, one or more control arguments. 

CONTROL ARGUMENTS 

-comment STR, -com STR 

allows the optional specification of a message to be displayed on the operators 
console at the time the volume set is to be detached. The comment text, STR, 
may be from 1 to 64 characters in length and must be quoted if it contains 
embedded white space. 

-display, -ds 

specifies that the entire detach description, after it has been parsed and any 
necessary defaults added, will be displayed on the user_output I/O switch. 

-unload 

specifies that any members of the volume set currently mounted are to be 
demounted at the time of detachment. 

-rewind 

specifies that any members of the volume set currently mounted are to be 
rewound to load point at the time of detachment. This is the default in the 
absence of the -unload control argument. 
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MODES OPERATION 

The mtape_ I/O module does not support the modes operation. 
POSITION OPERATION 

The mtape_ I/O module supports all appropriate positioning modes when the I/O 
switch is open for sequential_input~ 

READ LENGTH OPERATION 

The I/O switch must be open for sequential_input. 

READ RECORD OPERATION 

The I/O switch must be open for sequential_input. 

WRITE RECORD OPERATION 

The I/O switch must be open for sequential_output. Unlike previous tape I/O 
modules, non-mod .4 byte records may be written. 

QUERIES 

Under certain exceptional circumstances, the I/O module queries the user for 
information needed for processing to continue or instructions on how to proceed. 

Querying is performed by the command_query_ subroutine. The user may intercept 
one or more types of query by establishing a handler for the command_question 
condition, that is signalled by the command_query_ subroutine. Alternately, the answer 
command (described in the Muftics Commands and Active Functions Manual, Order 
No. AG92) can be used to intercept all queries. The use of a predetermined "yes" 
answer to any query causes those actions to be performed that attempt to complete an 
I/O operation without human intervention. 

In the following list of queries, status_code refers to command_question_info.status_code. 
See the MPM Reference Guide for information regarding the command_question 
condition and the command_question_info structure. 



status_code = error_table_$file_aborted 

This can occur only when the I/O switch is open for output. The I/O module 
is unable to correctly write file header labels, trailer labels, or tapemarks. This 
type of error invalidates the structure of the entire file set. Valid file set 
structure can only be restored by deleting the defective file or file section 
from the file set. 
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The user is queried for permission to delete the defective file or file section. 
If the response is "yes", the I/O module attempts deletion. The attempt may 
or may not succeed; the user is informed if the attempt fails. If the response 
is "no", no action is taken. The user will probably be unable to subsequently 
process the file, or append files to the file set; however, this choice permits 
retrieval of the defective file with another I/O module. In either case, the 
file is locked and no further I/O may be performed until the file is closed 
and subsequently re-opened. 

status_code = error_table_$unexpired_volume 

This can occur only when the I/O switch is open for output. A volume must 
be either reinitialized or overwritten; however, the first file or file section on 
the volume is unexpired. 

The user is queried for permission to initialize or overwrite the unexpired 
volume. If the response is "yes", the volume is initialized or overwritten and 
processing continues. If the response is "no", the file is locked and no further 
I/O may be performed until the file is closed and subsequently re-opened. 

status_code = error_table_$uninitialized_voIume 

A volume requires reinitialization or user verification before it can be used to 
perform any I/O. The I/O module distinguishes among two causes by setting 
command_question_info.query_code as follows: 

query _code = 2 

the first block of the tape is not a valid volume label for the 

volume type specified in the "-volume_type" attach description 

control argument This query code can occur only if the I/O 
switch is opened for output. 

query_code = 3 

the volume identifier recorded in the volume label is incorrect. 
The volume identifier does not match the volume name. 

If the I/O switch is opened for output, the user will be asked whether he 
wants to initialize or re-initialize the volume. If the response is "yes", the 
volume is reinitialized and processing continues. If the response is "no", the 
file is locked and no further I/O is possible without closing the I/O switch 
and subsequently re-opening. If the I/O switch is opened for input, the user 
will be asked whether he wants to continue processing in spite of the 
discrepancy. 

status_code = error_table_$unexpired_file 

This can occur only when the I/O switch is open for output. A file that must 
be extended, modified, regenerated, or replaced is unexpired. 

The user is queried for permission to overwrite the unexpired file. If the 

response is "yes", processing continues. If the response is "no", the file is 

locked and no further I/O is possible without closing the I/O switch and 
subsequently re-opening. 
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status_code = error_table_$no_next_volume 

This can occur when reading a multi volume file, or when writing a file and 
reaching physical end of tape. The I/O module is unable to determine the 
name of the next volume in the volume set. 

The user is queried for permission to terminate processing. If the response is 
"yes", no further processing is possible. If the I/O switch is open for output, 
the file is locked and no further I/O is possible without closing the I/O 
switch and subsequently re-opening. If the response is "no", the user is queried 
for the volume name of the next volume. (See status_code = 0 below.) 

status_code = 0 

This occurs only when the response to the above query is "no". The user is 
requested to supply the name of the next volume. The response may be a 
volume name, optionally followed by a mount message. Even if the volume 
name begins with a hyphen, it must not be preceded by the -volume control 
argument If a mount message is to be specified, the response takes the 
following form: 

volume name -comment STR 



ARGUMENTS 
STR 

is the mount message and need not be a contiguous string. See "Volume 

o ,:c: _i n.:. *t »i j * : " »< it ti 
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response. If a preset "yes" is supplied to all queries, this particular query never 
occurs. 

PER-FORMAT MODULES 

In order to process a variety of different tape volume formats, the mtape_ I/O 
module employs standard subroutine interfaces to what are known as Per-Format 
modules. The generic name of each of these Per-Format modules or subroutines is 
<vol_type>_tape_io_, where <vol_type> represents the identified name of the volume 
format which is to be processed. For this release, two Per-Format modules have been 
supplied. They are: 



ansi_tape_io_ 

For ANSI standard tape formats 

ibm_tape_io_ 

For IBM standard labeled, unlabeled and DOS tape formats 

See the ansi_tape_io_ module or the ibm_tape_io_ module for format-specific details 
of these two Per-Format modules. 
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In addition to the ANSI and IBM Per-Format modules, dummy versions of GCOS, 
Multics and RAW Per-Format modules have been provided as well. When one of 
these dummy Per-Format modules are selected, the Per-Format module initialization 
entry will display a message stating that the selected Per-Format module has not yet 
been fully implemented and then the attachment is aborted. 

Selection of the appropriate Per-Format module to process the desired volume set is 
performed at attach time. If a -volume_type control argument was specified in the 
attach description, then the value of this control argument is used exclusively in the 
selection of the Per-Format module. If no -volume_type control argument was present 
in the attach description, then volume type information returned by RCP after a 
successful volume mount is used to select the appropriate Per-Format module. In the 
event that the mounted volume was unreadable or of an unrecognized format, the 
value of the -default_volume_type control argument is used to select a Per-Format 
module. The selected Per-Format module is then found in the storage system via the 
standard object search rules. 

DATA BUFFERING AND CONTROL 

For the purposes of this discussion, a data buffer is defined to be a contiguous area 
of storage, in the ioi_workspace, in which the data to be written to one tape block is 
stored for tape output or which will contain the data from 1 tape block on tape 
input. The size of the data buffer determines the maximum size of the tape block to 
be written or read. There are two types of data buffers used by mtape_ and its 
Per-Format modules. These are synchronous and asynchronous buffers. 

Synchronous buffers are used to perform I/O on volume and file label records in a 
synchronous or one at a time manner. In the current implementation, only one of 
these buffers is allocated. 

Asynchronous buffers are used to perform I/O on user data being written to or read 
from a tape volume. These buffers are allocated after the I/O switch has been 
opened, when it can be determined what the block size will be, either from 
information in the file header labels or from the open description. As many of these 
asynchronous buffers are allocated as will fit in the users maximum workspace size, up 
to a maximum number of 16. Asynchronous buffers are deallocated when the I/O 
switch is detached or, when processing multiple files, upon opening subsequent files. 
As a performance feature, if it is determined that the buffers for the new file are to 
be the same size as those that were previously allocated, the buffers are not 
deallocated. This removes the necessity of re-allocating them. The size of the 
ioi_workspace is dynamically changed when allocating or deallocating buffers. 
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As the name implies, asynchronous buffers are used in an asynchronous manner, due 
to the write-behind and read-ahead features of mtape_. When the mtape_ I/O 
routine is called to write a block of data, no I/O is actually queued unless half of 
the buffers are filled. At this time, all filled buffers are queued for writing. Upon 
the next call to write a block, the mtape_ I/O routine will queue up the new block 
immediately, thus allowing this latest buffer to be linked into the current I/O channel 
program in an effort to keep the tape device running at rated speed if data is 
available to write. When reading data, a read is queued for all available buffers, each 
time a block is requested to be read. 

The reading and writing of data blocks (i.e. buffers), is completely demand driven 
from the Per-Format modules. Since the block format is Per-Format module 
dependent, and the unit of information passed in an iox_$read_record or iox_$write_record 
call is a logical record, which may or may not fill one or more blocks, only the 
Per-Format module in execution knows when a block is full or empty. The interface 
presented to the Per-Format modules by mtape_ is that of processing blocks of data 
in a synchronous manner. A pointer to the current buffer is maintained by the 
mtape_ I/O routine in a database which is common to both mtape_ and the 
Per-Format modules. The Per-Format module uses this pointer as if it was pointing 
to its only buffer. Each time a request is received by mtape_ to read or write a 
block, the current buffer pointer is incremented to the next buffer in the set, before 
control is returned to the Per-Format module. Physical file and block position 
counters are also maintained by mtape_ in the above mentioned common database. 
Whenever an exception condition presents itself which would cause the actual tape 
position to be different from that reflected in these counters (e.g. end of file 
condition, end of tape, etc.), the physical file and block position counters are 
re-synchronized before the exception condition is reported to the Per-Format module. 

In summary, the Per-Format module performs logical record multiplexing, while 
mtape_ performs block multiplexing. 

ARGUMENT PROCESSING 

With the advent of, and the mtape_ I/O modules use of, the new I/O system entries, 
iox_$open_file, iox_$close_file, and iox_$detach, the task of argument processing has 
become much more complex. In addition to a standard I/O system attach description, 
open, close and detach descriptions must also be processed to extract open, close and 
detach time control information. 

A new argument processing technology has been developed for mtape_ to reduce this 
complexity" and offer a centralized and consistent means of performing the essential 
task of argument processing for mtape_ and all of its associated Per-Format modules. 
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In order to implement this new argument processing technology, a few simple rules 
were imposed. They are: 

1. All "binary" control arguments (i.e. control arguments with no associated value) 
must have an antonym or inverse control argument to allow expressing the inverse 
state (e.g. -ring; -no_ring). 

2. Arguments are processed from left to right and all control arguments may appear 
multiple times. The right most value (or state, if a binary control argument) takes 
precedence at the exclusion of any previous values of the same control argument. 
(e.g. processing an attach description that includes "-den 1600 -ring -den 6250 
-no_ring" would yield "-den 6250 -no_ring"). 

3. With the exception of the allowable values of the -volume attach description 
control argument, any group of characters preceded by a "-" is assumed to be a 
control argument. 

4. With the exception of the volume names in the volume sequence list of an attach 
description, any group of characters that is not preceded by a "-" is assumed to 
be a value of the control argument last processed. 

DEFAULT VALUES 

As an ease of use feature, all control arguments and associated values that a user may 
specify in an attach, open, close or detach description, are supplied with reasonable 
default values by mtape_ and its associated Per-Format modules. For each description 
type, the supplied default values are stored in the data space of a standard value 
segment as an ASCII string. These strings are collectively known as "default_linear_forms", 
and have unique value names so that they can be readily associated with a particular 
description type. 

The default_linear_forms are found on the system, using the standard search_path 
mechanism, via the mtape_arguments search list. 

The default values are processed at the same time each description type is processed. 
Due to the left to right argument exclusion rule mentioned above in "Argument 
Processing", the insertion of default values is a simple matter. Whenever a particular 
description type is to be processed, the appropriate default_linear_form is found and 
processed before any user supplied description. After the default_linear_form has been 
processed, the user supplied description values are processed "on top" of the 
default_linear_form. The result is a combination of default as well as user supplied 
values, which make up a complete and unambiguous attach, open, close or detach 
description. 
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Although the mtape_ default values were picked to be reasonable and to fit most 
situations, it is well recognized that they may not be suitable for all tape processing 
needs at all sites or by all individuals. Therefore, a mechanism has been provided 
which will allow a site or an individual user to tailor their own default values to fit 
their particular needs. This user sellable default mechanism is embodied in three 
commands. The mtape_set_defaults, mtape_get_defaults and mtape_delete_defaults 
commands in concert will allow minipulation of default values. See the Multics 
Commands and Active Functions Manual, Order No. AG92 for a description of 
these commands. 



Name: rbf 

The rbf_ I/O module performs record oriented I/O to a remote I/O terminal that 
has the characteristics of the Honeywell Level 6M Satellite remote batch facility 
operating over an X.25 connection. The hardware options currently supported are 
defined by the control arguments described below. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

ATTACH DESCRIPTION 

rbf_ -control_args 

CONTROL ARGUMENTS 

are optional with the exception of -device, -comm, and -tty. All other control 
arguments are passed through as part of the attach description for the communications 
I/O module specified via -comm. 

-ascii 

uses the ASCII character set. This is the default. This argument is accepted for 
compatibility with other terminal I/O modules. 

-comm STR 

uses the communications I/O module specified by STR where STR must be "tty_". 
-device STR 

attaches the subdevice specified by STR. STR can be printer, punch, reader or 
teleprinter. 
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-physical_line_length N, — pll N 

specifies the physical line length, N, of the output device. This argument is 
accepted for compatibility with other terminal I/O modules. 



-terminal_type STR, -Up STR 

specifies the terminal type whose translation tables defined in the user or system 
terminal type table (TTT) are used to translate input and output to and from the 
device. If not specified, no translation is performed. Input and output translation 
tables can be up to 256 characters in length. 

-tty STR 

connects the remote I/O terminal to the logical communications channel named 
STR. 



OPEN OPERATION 



The rbf_ I/O module supports the sequential_input, sequential_output, and 
sequential_input_output opening modes. 

WRITE RECORD OPERATION 

The write_record entry performs the appropriate translation on the data record, 
converts the supplied slew control into the proper carriage control sequences for line 
printer attachments and performs data compression. The records are then transmitted 
to the specified communications channel. 

The format of the record supplied to this I/O module follows. This structure and the 
referenced constants are contained in terminal_io_record.incl.pll: 

dci I termi na l_i o_r ecord aligned based, 

2 version fixed bin, 

2 device_type fixed bin, 

2 s 1 ew_cont.ro 1 , 

3 slew_type fixed bin (18) unaligned unsigned, 

3 slew_count fixed bin (18) unaligned unsigned, 

f lags, 

3 binary bit(l) unaligned, 

3 preslew bit(l) unaligned, 

3 pad bit (3M unaligned, 

2 el ement_s i ze fixed bin, 
2 n_elements fixed bin {2k) , 

2 data, 

3 bits (termi nal_i o_record_n_e1 ements refer 
(term i na l_io_r ecord. n_el ements) ) 

bit (termi nal_i o_record_e 1 ement_s i ze refer 

(termi nal_io_record .el ement_s i ze) ) una! i gned; 
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STRUCTURE ELEMENTS 
version 

is the current version of this structure. This version of the structure is given by 
the value of the named constant terminal_io_record_version_l. 

device_type 

is the type of device to which this record is to be written. The acceptable values 
are TELEPRINTER.DEVICE, PRINTER.DEVICE, or PUNCH_DEVICE. 

slew_control 

need only be supplied by the caller if device_type is PRINTER_DEVICE and 
specifies the slew operation to be performed after printing the data in the record. 

slew_type 

specifies the type of slew operation. The possible values are SLEW_BY_COUNT, 
SLEW_TO_TOP_OF_PAGE, SLEW_TO_INSIDE_PAGE, 
SLEW_TO_OUTSIDE_PAGE, or SLEW_TO_CHANNEL. 

slew_count 

is interpreted according to the value of slew_control.slew_type. 
flags, binary 

must be set to "0"b. (This I/O module does not support binary data 
transmission.) 

flags, preslew 

must be set to "(To. (This I/O module does not support slew operations before 
printing the record's data.) 

element_size 

must be set to 9. (This I/O module only supports transmission of characters.) 
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n_elements 

is the number of characters in the record to be written. 

data, bits 

is the actual data. 

READ RECORD OPERATION 

The read_record entry reads characters from the communications channel and returns a 
single record from the device, basically performing tL ' .Verse of the functions 
described for the write_record operation. 

The format of the record this I/O module returns in the supplied buffer follows. 
This structure and the referenced constants are contained in terminal_io_record.incl.pll: 

del 1 termi nal_i o_record aligned based, 

2 version fixed bin, 

2 device_type fixed bin, 

2 s 1 ew_control , 

3 s I ew_ type fixed bin ( 1 8) unaligned unsigned, 

3 slew_count fixed bin (18) unaligned unsigned, 

flags, 

3 binary bit(l) unaligned, 

3 preslew bit(l) unaligned, 

3 pad bit (3*0 unaligned, 

2 el ement_s i ze fixed bin, 
2 n_elements fixed bin (24), 

2 data, 

3 bits (termi na l_i o_record_n_el ements refer 
(termi na l_i o_record . n_e 1 ements) ) 

bit (terminal_io_record_element_size refer 

(termi nal_io_record.element_si ze) ) unal igned; 

STRUCTURE ELEMENTS 



version 

is the current version of this structure. This version of the structure is given by 
the value of the named constant terminal_io_record_version_l. 

device_type 

is the type of device from which this record is read. Its possible values are 
TELEPRINTER_DEVICE or READERJDEVICE. 

slew_control. slew_ty pe 

is always set to SLEW_BY_COUNT. 

slew_control.slew_count 
is always set to 1. 
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flags, binary 

must be set to "0"b, 

flags, preslew 

must be set to "0"b. 

element_size 

must be set to 9. . 

n_elements 

is set to the number of characters returned in the record. 

data, bits 

is the actual returned data. 

CONTROL OPERATION 

This I/O module supports all the control operations supported by the tty_ I/O 
module. In addition, it supports the following: 

runout 

transmits any data stored in the output buffer. There is no input structure. 
end_write_mode 

prevents rbf_ from returning until all outstanding output has been written to the 
attached channel. There is no input structure. 

MODES OPERATION 

This I/O module supports the rawi, rawo, and 8bit modes. 
NOTES 

The select_device, reset, and binary_punch control orders are ignored, but are accepted 
for compatibility with other I/O modules. 
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Name: rdisk 

The rdisk_ I/O module supports I/O from /to disk packs. Sequential and indexed file 
types are supported. 

Entries in this module are not called directly by users; rather, the module is accessed 
through the I/O system. For a general description of the I/O system and a discussion 
of files, see the Programmer's Reference Manual. 

All errors encountered by rdisk_ are reported via the sub_err_ subroutine with the 
"flags" variable set to ACTION_DEFAULT_RESTART. The "info.ptr" variable passed 
to sub_err_ is set to null. 

ATTACH DESCRIPTION 

rdisk_ device_id pack_id {-control_args} 

ARGUMENTS 

device_id 

is a character string identifying the type number of the required disk device. The 
supported disk devices are listed in the table below, along with the character 
string to use for device_id: 

device id Device Type 



d 1 81 DSU181 

dl90 DSU190 

d 1 9 1 or dUOO DSU190/MSU0i+00 with the high-efficiency 

format {kO sectors/track) 

3380 MSU3380 

3381 MSU3381 
d451 MSU0451 
d500 MSU0500 
d501 MSU0501 



pack_id 

is a character string identifying the disk pack to be mounted. 
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CONTROL ARGUMENTS 

-device, -dv DEVICE_NAME 

indicates what disk drive DEVICE_NAME is to be attached. This is useful when 
attaching to drives that do not have removable media. DEVICE_NAME has the 
form of: 

dskX_NN{S} 

where: 

X 

is the subsystem name. 

NN 

is the device number. 

S 

is the subvolume name. Only valid for 3380 and 3381 device_ids. Valid 
subvolume names for 3380 are a and b, for the 3381 a, b and c. 

-size N 

indicates that the value of N is to override the value of the buff_len parameter 
as a record size limit for the read_record operation. (See "Notes" below.) 

-sys 

indicates that the attachment is being made by a system process and that a disk 
drive reserved for system functions is to be assigned. 

-write 

indicates that the disk pack may be written on. If omitted, the operator is 
instructed to mount the pack with the PROTECT button pressed so that writing is 
inhibited. 

NOTES 

The attachment causes the specified disk pack to be mounted on a drive of the 
specified type. 

When the -device option is given with a subvolume, rdisk_ will perform the address 
conversions in the same manner as the file system 10. More that one subvolume of a 
device may be attached by a process. The device may only be attached to one process 
at any one time. If the subvolume name is not given for a device that supports 
subvolumes, then rdisk_ will not convert the addresses and the entire device may be 
accessed. 
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OPENING 



The following opening modes are supported: 

sequential_input 

sequential_output 

sequential_update 

direct_input 

direct_update 

Notice that if the opening mode is of the output or update type, the attach 
description must include the -write control argument so that the operator does not 
press the PROTECT button when the pack is mounted. 

POSITION OPERATION 

This operation is supported for only the sequential_input and sequential_update opening 
modes. The type and quantity values are interpreted as follows: 

TYPE QUANTITY ACTION 

-1 — position to the beginning of the disk pack. 

+1 — position to the end of the disk pack. 

0 N skip N sectors (forward if N > 0; backward if N < 0). 

2 N position to sector N. 

READ RECORD OPERATION 

If the amount of data to be read does not terminate on a sector boundary, the excess 
portion of the last sector is discarded. A code of 0 is returned in this case. (See 
"Notes" below.) This operation is not supported for the sequential_output opening 
mode. 

REWRITE RECORD OPERATION 

If the amount of data to be written does not terminate on a sector boundary, the 
remaining portion of the last sector is filled with spaces in sequential modes and 
binary zeros in direct modes. A code of 0 is returned in this case. (See "Notes" 
below.) This operation is supported for only the update opening modes. 

SEEK KEY OPERATION 

This operation returns a status code of 0 for any key that is a valid sector number. 
The record length returned is always 256 (current physical sector size in characters) 
for any valid key. The specified key must be a character string that could have been 
produced by editing through a PL/I picture of "(8)9". (See "Notes" below.) This 
operation is supported for only the direct opening modes. 
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LI Of 

The following orders are supported when the I/O switch is open, except for 
getbounds, which is supported while the switch is attached. 

changepack 

causes the current pack to be dismounted and another pack to be mounted in its 
place. The info_ptr should point to a varying character string (maximum of 32 
characters) containing the identifier of the pack to be mounted. This operation is 
not allowed for MSU0500 or MSU0501 devices. 

device_info 

causes information pertaining to the attached disk device to be returned to the 
user. The info_ptr should point to a structure of the following form: 

del 1 device_info_table aligned, 

2 subsystem_name char (k) , 

2 device_name char (8), 

2 sect_per_dev fixed bin (35) » 

2 cyl_per_dev fixed bin, 

2 sect_per_cyl fixed bin, 

2 sect_per_track fixed bin, 

2 num_l abel_sect fixed bin, 

2 num_a 1 t_sect fixed bin, 

2 sect_size fixed bin (12); 

where: 

subsystem_name 

is the name of the disk subsystem in use (i.e., D191). 

device_name 

is the name of the disk device in use (i.e., dska_04). 
sect_per_dev 

is the total number of non-T&D sectors on the disk pack. 
cyl_per_dev 

is the total number of non-T&D cylinders on the disk pack. 
sect_per_cyl 

is the number of data sectors on each cylinder of a disk pack. 

sect_per_track 

is the number of data sectors on each track. 



is the number of data sectors to reserve for label information. 
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num_alt_sect 

is the number of data sectors to reserve for alternate track area. 
sect_size 

is the number of 36-bit words in each data sector. 
format_trk 

causes a format track command to be issued to the track that was indicated by a 
preceding seek_key operation. This operation is not allowed for MUS0500 or 
MSU0501 devices. The info_ptr should point to a user supplied structure of the 
following form: 

del 1 f ormat_trk_i nf o aligned, 
(2 hz " bit (2) , 

2 ti bit (2) , 

2 adcyl f ixed bin (16) , 

2 adhd fixed bin (16)) unaligned; 

where: 
hz 

is a bit pattern indicating the state of the header bypass switch. The hz bits 

are defined as follows: 

h z bit pattern meaning. 

0 0 format home address and all data records. 

0 1 verify home address and record one, format home address 

and all data records. 

1 0 skip home address, format all data records. 

1 1 verify home address and data record one, skip home address 
and format all data records. 

ti 

is a bit pattern indicating the state of the track indicator bits. The ti bits 

are defined as follows: 

t i bit pattern meaning. 

0 0 format track good. 

0 1 format track alternate. 

1 0 format track defective with alternate track assigned. 

1 1 format track defective with no alternate track assigned. 

adcyl, adhd 

are the alternate or defective cylinder and head numbers used when the track 
indicator bits equal "01"b or "10"b. These two fields are defined as follows: 

1. If the track indicator bits are set to "01"b (alternate track), then adcyl and 
adhd should be equal to the defective cylinder and head number for which the 
alternate track is being formatted. 
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2. If the track indicator bits are set to "10"b (defective with alternate assigned), 
then adcyl and adhd should be equal to the cylinder and head number of the 
alternate track. 

getbounds 

causes the lowest and highest sector numbers accessible by the caller under the 

current modes to be returned. The info_ptr should point to a structure of the 
following form: 

del 1 bounds, 

2 low fixed bin (35) , 

2 high fixed b i n (35) ; 



rd_trk_header 

causes a read track header command to be issued to the track that was indicated 
by a preceding seek_key operation. This operation is not allowed for MUS0500 or 
MSU0501 devices. The raw track header information is passed to the user in a 
structure (pointed to by info_ptr) of the following form: 

del 1 trk_header_i nf o aligned, 



(2 ha_cyl 


b' 


t 


(16) , 


2 ha head 


b' 


t 


(16) , 


2 padl 


b" 
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2 ha ti 


b" 
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(2) , 


2 pad2 


bi 
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(10) , 


2 rcd_0_ti 


b" 
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(2), 


2 rcd_0_cyl 
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(16), 


2 rcd_0_head 
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(16) , 


2 red 0 rn 
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(8), 


2 pad 3 


b' 
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{2k), 


2 red 0 data 


(8), b' 
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(8), 


2 pad** 


b' 
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{h) ) unal i gned ; 



where: 
ha_cyl 

is the cylinder number read from the track home address. 
ha_head 

is the head number read from the track home address. 
ha_ti 

is the track indicator bits (defined above in the format_trk order) read from 
the track home address. 
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rcd_0_ti 

is the track indicator bits read from record zero. If the ha_ti bits indicate 
"10"b, then rcd_0_ti should equal "01"b for alternate track. If ha_ti indicates 
"01"b, then rcd_0_ti should equal "10"b for defective track. Otherwise 
rcd_0_ti will equal ha_ti. 

rcd_0_cy, rcd_0_head 

are the cylinder and head number read from record zero. If ha_ti indicates 
"10"b, then rcd_0_cyl and rcd_0_head equal the cylinder and head number of 
the alternate track. If ha_ti indicates "01"b, then rcd_0_cyl and rcd_0_head 
contain the cylinder and head number of the defective track. Otherwise, 
rcd_0_cyl and rcd_0_head equal ha_cyl and hajiead. 

rcd_0_rn 

is the record number for record zero (normally equal to zero). 
rcd_0_data 

is the eight data bytes in record zero (not a normal data record) and is 
normally equal to zero. 

padn 

are unused bits that are returned as "0"b. 

tsize 

causes the value of the record size override setting to be reset. The info_ptr 
should point to an aligned fixed binary(35) quantity containing the new override 

value, 

MODES OPERATION 

The modes operation is supported when the I/O switch is attached. The recognized 
modes are listed below. Each mode has a complement indicated by the circumflex 
character (~) that turns the mode off. 

label, A label 

specifies that a system -defined number of sectors at the beginning of the pack 
are reserved for a pack label, and that a seek_key or position operation is to 
treat any key or position within this area as an invalid key. (The default is on.) 

raw, A raw 

specifies that the entire disk pack is available to the user, including the T&D 
cylinder (the last cylinder on the disk pack). (The default is off.) 

alttrk, A alttrk 

specifies that the pack has been formatted with the assignment of alternate tracks, 
so that a system -defined number of sectors at the end of the pack are reserved 
for an alternate track area. Therefore, a seek_key or position operation is to 
treat any key within that area as an invalid key. (The default is off.) This mode 
cannot be enabled for a MSU0500 or MSU0501 disk. 
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wrtcrnp, A wrtcmp 

specifies that the write-and-compare instruction, rather than the write instruction, 
is used for the rewrite_record operation. This causes all data written to be read 
back and compared to the data as it was prior to being written. This mode 
should be used with discretion, since it doubles the data transfer time of every 
write. (The default is off.) 

WRITE RECORD OPERATION 

If the amount of data to be written does not terminate on a sector boundary, the 
remaining portion of the last sector is filled with spaces. A code of 0 is returned in 
this case. (See "Notes" below.) This operation is supported for only the sequential_output 
opening mode. A series of writes will write successive records. 

CLOSING 

The closing has no effect on the physical device. For the sequential_output opening 
mode, the effect is as if an end-of-file flag is placed just beyond the end of the 
available disk area. 

DETACHING 

The detachment causes the disk pack to be detached from the users process. 
NOTES 

This I/O module is a very elementary, physical-device-oriented I/O facility, providing 
the basic user -level interface to a disk device. All operations are performed through 
calls to various I/O interfacer (IOI) mechanisms and resource control package (RCP) 
entries. Certain conditions must be satisfied before a user process can make use of 
this facility: 

1. The system must be configured with one or more disk drives available as I/O 
disks. 

2. The user must have access to assign the disk drive with RCP, access to the IOI 
gates, and access to the "acs" segment (e.g., >scl>rcp>dskb_l8.acs) that is 
used by the site to control access to the disk drive. 

For input and update opening modes, the file occupies the entire available disk area 
(see the getbounds control order). For the sequential_output opening mode, the file is 
considered to be empty. That is, an open followed by a write records data in the 
first sector of the available disk area. 

For direct opening modes, the entire disk pack is treated as an indexed file, with keys 
interpreted literally as physical sector numbers. Hence, the only allowable keys are 
those that can be converted into fixed binary integers that fall within the range of 
valid sector numbers for the given disk device under the current modes, as returned 
by the getbounds control operation. 
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For the sequentiaMnput and sequential_update opening modes, if an attempt is made 
to read beyond the end of the user-accessible area, the code error_table_$end_of_info 
is returned. For all other opening modes, if an attempt is made to read or write 
beyond the end of the user-accessible area on disk, the code error_table_$device_end 
is returned. If a defective track is encountered or if any other unrecoverable data 
transmission error is encountered, the code error_table_$device_parity is returned. 

The record length is specified through the buff_len parameter in the read_record 
operation, and through the rec_len parameter for the write and rewrite operations, 
unless overridden by a -size control argument in the attach description, or by a 
setsize control order. 

The following items must be considered when using this I/O module with language 
input/ output: 

DEVICE ATTACHMENT AND FILE OPENING 

PL/I: A file can be attached to a disk pack in PL/I by specifying the 

appropriate attach description in the title option of an open statement. 
After opening, the desired modes should be set and the current sector 
bounds should be obtained through direct calls to pll_io_$get_iocb_ptr, 
iox_$modes, and iox_$control. 

FORTRAN: It is not possible to attach a file to a disk pack within FORTRAN. 

Here, the attachment must be made external to the FORTRAN program, 
e.g., through the io_call command or through use of a PL/I subroutine. 
FORTRAN automatically opens the file with the appropriate attributes. 
Also, it is impossible to set modes or obtain sector bounds from within 
FORTRAN. This should be done through use of a PL/ 1 subroutine 
prior to the first FORTRAN reference to the file. 

INPUT 

PL/ 1: The input record length (buff_len) is determined by the size of the 

variable specified in the into option. 

For the sequentiaMnput and sequential_update opening modes, use the 
PL /I read statement with the into option to read data. Use the ignore 
option to skip forward within the file. An open statement followed by 
a read statement will read in the first record. Successive reads will 
obtain successive records. 

For the direct_input opening mode, use the PL/ 1 read statement with 
the into and key options. The set option should not be used. The key 
should be a character string containing the character representation of 
the desired sector number. 

The PL/ 1 get statement can be used with the sequentiaMnput opening 
mode if the record_stream_ I/O module is referenced in . the attach 
description of the open statement 
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FORTRAN: In FORTRAN, buff Jen has no relationship to input variable size. 

Hence, the -size control argument must be specified in the attach 
description if the disk pack is to be read through FORTRAN. The size 
should be set to the length of the longest expected record. 

For the sequential_input opening mode, use the unformatted sequential 
read statement. 



For the direct_input opening mode, use the unformatted keyed version 
of the FORTRAN read statement. The key must be an integer, whose 
value is the desired sector number. 



OUTPUT 

PL/ P. The size of the variable referenced in the from option determines the 

length of the record written to disk. 

For the sequential_output opening mode, use the write statement with 
the from option. An open statement followed by a write statement will 
start writing at the beginning of the available area on the disk pack. 



For the sequential_update opening mode, use the rewrite statement with 
the from option. A previous read statement must have been used to 
designate which record will be updated. 

For the direct_update opening mode, use the rewrite statement with the 
from and key options. The key should be a character string containing 
the character representation of the desired sector number. 

The PL/ 1 put statement can be used with the sequentiaLoutput opening 
mode if the record_stream_ I/O module is referenced in the attach 
description of the open statement. 

FORTRAN: The size of the output record is determined by the amount of data 
specified in the write list. 

For the sequentiaLoutput opening mode, use the unformatted sequential 
write version of the FORTRAN write statement. 



For the direct_update opening mode, use the unformatted keyed version 
of the write statement. The key should be a character string containing 
the character representation of the desired sector number. 



CONTROL OPERATIONS FROM COMMAND LEVEL 



All control operations may be performed from the io_call command, as follows: 



io_call control switch order_arg 
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record_stream. 



where: 
switch 

is the name of the I/O switch. 

order_arg 

must be one of the following: 

changepack newpack 
setsize newsize 
getbounds 

where: 

newpack is the name of the new pack to be mounted, 
newsize is the new record size in words. 



Name: record stream 

The record_stream_ I/O module attaches an I/O switch to a target I/O switch so 
that record I/O operations on the attached switch are translated into stream I/O 
operations on the target switch, or so that stream I/O operations on the attached 
switch are translated into record I/O operations on the target switch. In this way a 
program that uses only record I/O may process unstructured files and do I/O 
from /to the terminal. Similarly a program that uses only stream I/O may process 
some structured files. 

Entry points in this module are not called directly by users; rather the module is 
accessed through the I/O system. 

ATTACH DESCRIPTION 

record_stream_ {swi tch_name} {-control_args} 

ARGUMENTS 

switch_name 

is the name of the target I/O switch. It heed not be attached when this 
attachment is made. If this argument is omitted, the -target control argument 
must be present. 
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CONTROL ARGUMENTS 

The following control the transformation of records into a stream of bytes and vice 
versa, or control the target attachment: 

-nnl 

transforms a record into a stream without appending a newline character, 
-length N 

converts the stream of bytes to a sequence of records each of which has length 
N. 

-target attach_descrip 

specifies the attachment of a uniquely named target switch. This control argument 
must occur if and only if the switch_name argument is omitted, and it must be 
the last control argument in the attach description, if present. 

If neither the -nnl nor -length control arguments are given, lines are transformed into 
records after deleting trailing newlines and records are transformed into lines by 
appending newiines. 

OPENING 

The attached I/O switch may be opened for stream_input, stream_output, sequential_input, 
or sequential_output. The implications of the opening mode are as follows: 

stream_input 

The target I/O switch must be either open for sequential_input, open for 
sequential_input_output, or attached and closed. In the last case, it is opened for 
sequential_input. The sequence of records read from the target switch is 
transformed into a stream of bytes that are transmitted to the calling program by 
the get_line and get_chars operations. The read_record operation is used to read 
the records from the target switch. 

stream_output 

The target I/O switch must be either open for sequential_output, open for 
sequential_input_output, or attached and closed. In the last case, it is opened for 
sequential_outpuL The stream of bytes written to the attached switch by the 
put_chars operation is transformed into a sequence of records that are written to 
the target switch by use of the write_record operation. 

sequential__input 

The target I/O switch must be either open for stream_input, open for 
stream_input_output, or attached and closed. In the last case, it is opened for 
stream_input. The stream of bytes read from the target switch is transformed into 
a sequence of records that are transmitted to the calling program by read_record 
operations. If the attach description specifies the default line to record 
transformation, the get_line operation is used to read bytes from the target 
switch. If the attach description specifies the -length control argument, the 
get_chars operation is used to read bytes from the target switch. 
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sequential_output 

The target I/O switch must be either open for stream_output, open for 
stream_input_output, or attached and closed. In the last case, it is opened for 
stream_output. The sequence of bytes written to the attached switch by the 
write_record operation is transformed into a stream of bytes that are written to 
the target switch by use of the put_chars operation. 

TRANSFORMATIONS 

The transformation from record to stream form can be described in terms of taking 
records from a record switch and giving bytes to a stream switch, and similarly for 
stream to record (a record is a string of bytes). Which switch is the record switch 
and which the stream switch depends on the opening mode as explained previously 
under "Opening." The transformation is determined by the control arguments in the 
attach description. The details are as follows: 



Record to stream: 
(default) 



A record is taken from the record switch, a newline 
character is appended, and the resulting string is given to 
the stream switch. 



-nnl 



A record is taken from the record switch and given to the 
stream switch without modification. 



Stream to record 
(default) 



A line (string of bytes ending with a newline character) is 

taken from the stream switch, the newline character is 

deleted, and the resulting string is given to the record 
switch. 



-length N 



To form a record, N bytes are taken from the 
switch and given to the record switch as one record. 



stream 



BUFFERING 

The I/O module may hold data in buffers between operations when the switch is 
opened for stream_output, stream_input, or sequential_input. 

CLOSE OPERATION 

The I/O module closes the target switch if and only if the I/O module opened it. 
DETACH OPERATION 



The I/O module detaches the target switch if and only if the I/O module attached it 
via the -target control argument. 
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POSITION OPERATION 

Only positioning to the beginning of file or end of file and skipping forward are 
supported, except in the default sequential case, which also permits backward skipping. 
These operations are only supported to the extent the attachment of the target I/O 
switch supports them. 

CONTROL AND MODES OPERATIONS 

These are supported for open switches in the sense that they are passed along to the 
I/O module for the target switch. 

IN PUT I OUT PUT STATUS 

In addition to the I/O status codes specified in the description of the iox_ subroutine 
for the various I/O operations, this I/O module returns codes returned by the target 
switch I/O module. 

EXAMPLES 

The following commands permit sequential input operations from the user's terminal: 

io_call attach sysin record_stream_ user_input 

io_call open sysin sequent i a 1 i nput 

Each record accessed through sysin corresponds to a line read through user_input, with 
its trailing newline character deleted. 

Consider a PL/1 statement of the form: 

open file(x) title ("record_stream_ -target vf i 1 e_ seg") {open i ng_mode} ; 

The opening_mode argument may be one of the following: 

stream_input 
stream_output 
sequential_input 
sequential_output 

Sequential operations on file(x) generate stream operations on seg and vice versa, with 
lines transformed into records without trailing newlines or records transformed into 
lines by appending newlines, depending upon the mode of opening. 



3-134 



AG93-05 



record_stream_ remote_input_ 



Consider the command: 

io_call attach switchxx record_stream_ -length 100 -target vfile_ seg 

If switchxx is opened for stream_input, seg must be an existing unstructured file. The 
effect is equivalent to that of inserting a newline after every 100 characters of seg 
referenced by get_chars, get_line, or position operations through switchxx. 

Alternately, switchxx may be opened for sequential_output. In this case, variable length 
records written through switchxx are given trailing newlines and restructured into 
100-character records, which are then transmitted to the sequential file, seg. 



Name: remote input 

The remote_input_ I/O module performs record input from a terminal I/O module, 
which is assumed to be connected to a remote I/O device, such as a Honeywell Level 
6 remote batch facility (G115 type), an IBM 2780, or an IBM 3780. Except for 
hardware restrictions, this module performs some code conversion and control in such 
a way that remote and local card reading are the same. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

This module in turn constructs an attach description for the module specified in the 
-terminal control argument, passing the other attach information specified by the 
caller. 

ATTACH DESCRIPTION 

remote_i nput_ -control_args 
CONTROL ARGUMENTS 
-device STR 

STR defines the device type that this I/O module is attempting to simulate. The 
acceptable values for STR are reader, printer_in, and punch_in. This control 
argument is optional. If not supplied, a device type of reader is assumed. 

-physical_line_length N, -pii N 

This control argument is accepted and ignored for compatibility with other 
device-level I/O modules. It is not passed on to the terminal I/O module. 

-record_len N 

defines the maximum record length (buffer size) for data from the terminal I/O 
module in characters. The accepted ranges are 80 to 160 for the device type of 
reader, and 10 to 1024 otherwise. If this control argument is not given, the 
maximum for the device type is assumed. 
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-runout_spacing N, -runsp N 

This control argument is accepted and ignored for compatibility with other 
device-level I/O modules. It is not passed on to the terminal I/O module. 

-terminal STR 

STR specifies the terminal I/O module to be attached by this device I/O module. 
(Required) 

All other attach control arguments are assumed to belong to the terminal I/O module. 
These are passed on as part of its attach description. The -device option passed on to 
the terminal I/O module specifies one of the following devices: reader, printer, or 
punch. See the description of the terminal I/O module for a full definition of 
required and optional control arguments. 

OPEN OPERATION 

The remote input I/O module supports the stream_input opening mode. The terminal 
I/O module switch is in turn opened with the sequential_input or stream_input modes. 

GET CHARS OPERATION 

The get_chars entry reads one record from the terminal I/O module and returns up 
to the number of specified characters. If the number of characters in the record is 
greater than the requested number, error_table_$data_loss is returned along with the 
data. 

CONTROL OPERATION 

The remote_input_ device I/O module supports the following control operations: 
get_count 

returns the current record count. This is the count of records read from the 
terminal I/O module since the last reset control operation. This operation is not 
passed on to the terminal I/O module. 

The info_pointer must point to the following structure. (This structure is taken 
from the counts structure in prt_order_info.incl.pll for compatibility with 
procedures that use several device I/O modules.) 

del 1 counts aligned based, 

2 pr t__data_pad (4) fixed bin, 
2 record_count fixed bin (35) » 
2 prt_pad fixed bin; 

The variable record_count will contain the returned value. This corresponds with 
the variable line_count from the other structure. 

reset 

sets the current record count to 0 and passes the control operation on to the 
terminal I/O module. 
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All other control operations are passed on to 
MODES OPERATION 

This I/O module supports the modes defined 
the attach description. 



remote_printer 



the terminal I/O module. 



by the terminal I/O module specified in 



Name: remote printer 

The remote_printer_ I/O module presents a stream I/O interface to the caller and 
performs record output to a printer, which is assumed to be part of a remote I/O 
device, such as a Honeywell Level 6 remote batch facility (G115 type), an IBM 2780, 
or an IBM 3780. Except for hardware restrictions, this module performs all the 
necessary code conversion and control in such a way that remote and local printing 
are the same. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

This module in turn constructs an attach description for the module specified in the 
-terminal control argument, passing the attach information for horizontal tabbing, 
physical line length, and all other attach information specified by the caller. 

ATTACH DESCRIPTION 

remote_pr i nter_ -control_args 

CONTROL ARGUMENTS 

The following control arguments are optional, with the exception of -terminal: 

-horizontal_tab, -htab 

printer has a horizontal tab feature. The default is no tab control. 

-physical_line_length N, -pll N 

printer has a maximum line width of N characters. The default is 132 characters. 

-physical_page_length N, -ppl N 

printer has a maximum line count per page of N. The default is 66 lines. 

-terminal STR 

uses the terminal I/O module specified by STR. This control argument is 
required. 

OPEN OPERATION 

The remote printer I/O module supports the stream_output opening mode. 
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PUT CHARS OPERATION 

The put_chars entry converts a character string delimited by a newline character to an 
image suitable for printing and transmits this image to the terminal I/O module. This 
operation is repeated until all the characters specified by the caller have been 
transmitted. 

CONTROL OPERATION 

This I/O module supports all the control operations supported by the terminal I/O 
module specified in the attach description. In addition, it supports the following 
control orders: 



channel_stops 

sets the channel stop data used for slew to channel control sequences during a 
put_chars operation. The info pointer defines the channel_stops input array as 
found in the prt_order_info include file. Array element N defines the stops for 
line number N. Bit M of an array element defines a stop for channel M. The 
initial value is no slops defined. Once defined, ihe stops remain in effect until 
the next channel_stops control operation. 

end_of_page 

advances the paper to the bottom of the current page, one line below the point 
where page labels are printed. If page labels are set the label is printed. The 
info pointer is not used and may be null. 

get_count 

returns accounting information. The info pointer defines the counts output 
structure as found in the prt_order_info include file. The page and line counts 
are reset by the reset control operation. 

get_error_count 

returns the error count since the output module was attached. The info pointer 

defines the output variable ret_error_count as found in the prt_order_info include 
file. 

get_position 

returns the position data defined by the position_data structure in the prt_order_info 
include file. The data resembles that of the get_count control operation, but the 
structure adds the total characters printed since the last reset to allow the caller 
to start the next put_chars operation at the following character when the module 
returns due to lpg or stopN mode. The data structure is also used for the 
set_position operation (see below). 

inside_page 

advances the paper to the formfeed position of the next inside page. An inside 
page is a top page when the listing is folded correctly. Separator bars for the 
head sheet are printed over the perforations at the bottom of an inside page. The 
info pointer is not used and may be null. 
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outside_page 

advances the paper to the formfeed position of the next outside page. An outside 
page is a bottom page when the listing is folded correctly. The info pointer is 
not used and may be null. 

page_labels 

sets the top and bottom page labels to be printed for each logical page. The info 
pointer may be null to reset page labels to blank. Otherwise, the info pointer 
defines the page_labels input structure as found in the prt_order_info include file. 

paper_info 

sets the physical characteristics of the paper in the printer. The info pointer 
defines the paper_info input structure as found in the prt_order_info include file. 
Once set, the paper_info remains in effect until the next paper_info control 
operation. If the printer has a software loadable VFC image, a new image is 
loaded and the printer placed out of synchronization for the operator to align the 
paper. Otherwise, the code error_table_$no_operation is returned so the caller can 
request the operator to load the appropriate VFU tape and set the required lines 
per inch switch to complete the operation. The defaults are: page length, 66; line 
length, 136; lines per inch, 6. 

reset 

resets the output module to its default state: default modes, no page labels, line 
count = 0, page count = 1, and total chars = 0. The info pointer is not used 
and may be null. 

resetwrite 

cancels any data buffered for output. It is used to clear the output module after 
an error so the paper can be resynchronized. The info pointer is not used and 
may be null. 

runout 

causes all buffered data to be output before returning to the caller. It is used to 
synchronize the program with the actual device. The info pointer is not used and 
may be null. 

set_position 

sets the internal counters in the output module. The info pointer defines the 
position_data input structure as found in the prt_order_info include file. This is 
the reverse of the get_position control operation. It is used to start the 
accounting data at the correct point when restarting an I/O daemon request in 
the middle. 
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MODES OPERATION 

This I/O module supports all the modes supported by the terminal I/O module 
specified in the attach description. In addition, it supports the following modes: 



Ipg. A lPg 

causes the output module to return to the caller when the end of the current 
page is reached (i.e., at the formfeed position for the next logical page). If there 
are unprocessed characters at this point, the code error_table_$request_pending is 
returned. The default is ~lpg- 

ctl_char, A ctl_char 

causes the output module to pass nonprinting characters to the device as is. 
Carriage movement characters (newline, formfeed, carriage return, backspace, and 
horizontal and vertical tab) are interpreted normally. The ASCII escape character 
(octal 033) is also transmitted directly, unless esc mode is enabled. If ctl_char 
mode is disabled, the treatment of nonprinting characters is determined by the 
setting of non_edi ted mode. The default is "ctl_char. 

esc, A esc 

enables searching for escape sequences in the input string, which enables slew to 
channel orders. The default is ~esc. 

non_edited, A non_edited 

causes the output module to print the applicable octal ASCII code preceded by a 
backslash (\) for nonprinting characters, and to use the nonedited output 
conversion table in the specified 111 for the remote device. The ~non_edited 
value causes any such characters to be omitted from the output. The setting of 
this mode is ignored when ctl_char is in effect. The default is ~non_ed i ted, 

noskip, A noskip 

suppresses the automatic insertion of blank lines at the end of a logical page (i.e., 
it allows the printer to print over the perforations). It has the side effect of 
setting the logical page length to its default value. The default is ^noskip. 

print, A print 

specifies that processed characters from the input string are to be printed. The 
Sprint value allows a string to be processed for output, sets page and line 
counts, and honors the Ipg and stopN modes, but without actually printing the 
processed characters. The default is print. 

single, A single 

specifies that any formfeed or vertical tab characters from the input string are to 
be converted to newline characters (i.e., it suppresses runaway paper feeding). The 
default is "single. 
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truncate, A truncate 

truncates the output if the line exceeds the line length. The ^truncate value 
allows the line to be wrapped onto the next line if it is too long. The default is 
^truncate. 

plN 

sets the logical page length to N lines. At the end of a logical page, the printer 
skips to the next formfeed position (unless noskip mode is set). The value of N 
must be greater than one, and can be greater than a physical page. The default 
value is physical page length minus lines per inch. 

UN 

sets the logical line length to N characters. The value of N must be greater than 
the indentation (see below) and must not be greater than the physical line length 
of the device. The default value is the physical line length. 

inN 

sets the indentation to N characters. The value of N must be 0 or a positive 
integer which is less than the logical line length. The default value is 0. 

stopN 

sets the output module to return to the caller every N pages even though the 
processing of the input string has not been completed; If there is unprocessed 
input remaining, a code of error_table_$request_pending is returned. A value of 0 
means do not return until all input is processed. The counter of how many pages 
to process before returning is reset when a new value is given. The default value 
is 0. 

default 

causes all of the above modes to be reset to their default values. This mode is 
also passed to the terminal I/O module for processing. 

POSITION OPERATION 

This I/O module supports all the position operations supported by the terminal I/O 
module specified in the attach description. 
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Name: remote punch 

The remote_punch_ I/O module presents a stream I/O interface to the caller and 
performs record output to a card punch, which is assumed to be part of a remote 
I/O device, such as a Honeywell Level 6 remote batch facility (G115 type), an IBM 
2780, or an IBM 3780. Except for hardware restrictions, this module performs all the 
necessary code conversion and control in such a way that remote and local card 
punching are the same. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

This module in turn constructs an attach description for the module specified in the 
-terminal control argument, passing the other attach information specified by the 
caller. 

ATTACH DESCRIPTION 

remote_punch_ -control_arg 
CONTROL ARGUMENTS 
-card_ll N 

specifies the length of records (cards) supported by the terminal I/O module. 
(Default is 80.) 

-device STR 

defines the type of device to be simulated by this I/O module and can be either 
"punch" or "reader_simulator". This specification is passed to the terminal I/O 
module as "-device punch" or "-device reader", respectively. (Default is "punch".) 

-horizontal_tab, -htab 

specifies that the device supports the horizontal tab character. (Default is the use 
of the appropriate number of spaces.) 

-non_edited 

specifies that nonprinting characters can be passed directly to the terminal I/O 
module. (Default is that these characters are not passed.) 

-runout_spacing N, -rasp N 
-physical_page_length N, -ppl N 

are accepted and ignored for compatibility with other device I/O modules. 

-terminal STR 

STR specifies the terminal I/O module to be attached to this device I/O module. 
(Required) 

All other attach arguments are passed directly to the terminal I/O module. 
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OPEN OPERATION 

The remote punch I/O module supports the stream_output opening mode. 
PUT CHARS OPERATION 

The put_chars entry splits the data to be written into records of the size given by 
-card_ll and transmits these records to the terminal I/O module. This operation is 
repeated until all the characters specified by the caller have been transmitted. 

CONTROL OPERATION 

The remote_punch device I/O module supports the following control operations: 
binary_punch 

requests that all subsequent data be punched in binary (rather than RMCC) if 
supported by the terminal I/O module. This control order is then passed on to 
the terminal I/O module. 

get_count 

returns the current record count, which is the number of records written to the 
terminal I/O module since the last reset control operation. This operation is not 
passed on to the terminal I/O module. The info_ptr must point to the following 
PL/1 structure. (This structure is taken from the counts structure in 
prt_order_info.incl.pll for compatibility with procedures that use several device 
I/O modules.) 

del 1 counts aligned based, 

2 prt_data_pad (4) fixed bin, 
2 record_count fixed bin (35) » 
2 prt_pad fixed bin; 

The variable record_count will contain the returned value. This corresponds with 
the variable line_count from the other structure. 

reset 

sets the current record count to zero, returns to punching in RMCC (remote 
Multics card code), and passes the order to the terminal I/O module. 

All other control operations are passed directly to the terminal I/O module for 
processing. 

MODES OPERATION 

This I/O module supports the RMCC output card mode defined in the Programmer's 

Reference Manual. It also supports the two modes non_edited and default, which 

enable and disable edited output conversion, if output conversion has been enabled by 
the terminal I/O module. 
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POSITION OPERATION 

This I/O module supports all the position 
module specified in the attach description. 



operations supported by the terminal I/O 



Name: remote teleprinter^. 

The Temote_teleprinter_ I/O module presents a stream I/O interface to the caller and 
performs record I/O to a terminal or printer, which is assumed to be part of a 
remote I/O device, such as a Honeywell Level 6 remote batch facility (G115 type), an 
IBM 2780, or an IBM 3780. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. 

This module in turn constructs an attach description for the module specified in the 
-terminal control argument, passing the attach information for ASCII or EBCDIC, 
horizontal tabbing, physical line length, and all other attach information specified by 
the caller. 

ATTACH DESCRIPTION 

remote_tel epr i nter_ -control_args 
CONTROL ARGUMENTS 

The following control arguments are optional, with the exception of -terminal: 

-horizontal_tab, -htab 

output device has a horizontal tab feature. The default is no tab control. 

-physical_line_length N, -pll N 

output device has a maximum line width of N characters. The default is 80 
characters. 

-physical_page_length N, -ppl N 

output device has a maximum line count per page of N. The default is 66 lines. 

-runout_spacing N, -runsp N 

outputs N newline characters with each runout operation. This allows the operator 
to see messages still under the printer mechanism for terminals that have only a 
printer as an output device. The default is 0. 



uses the terminal I/O module specified by STR. This control_arg is required. 
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OPEN OPERATION 

The remote_teleprinter_ I/O module supports the stream_input_output opening mode. 
PUT CHARS OPERATION 

The put_chars entry converts a character string ending in a newline character to an 
image suitable for printing and transmits this image to the terminal I/O module. 

GET CHARS OPERATION 

The get_chars entry reads the number of specified characters from the terminal I/O 
module. 

GET LINE OPERATION 

The get_line entry reads one record from the terminal I/O module, appends a new 
line, and returns as many characters as requested by the caller, or the whole record if 
it is shorter. If the record is longer than requested, error_table_$data_loss is returned. 

CONTROL OPERATION 

This I/O module supports all the control operations supported by the terminal I/O 
module specified in the attach description. In addition, it supports all the control 
operations supported by the I/O module remote_printer_. 

MODES OPERATION 

This I/O module supports all the modes supported by the terminal I/O module 
specified in the attach description. In addition, it supports all the modes supported by 
the I/O module remote_ printer_. 

POSITION OPERATION 

This I/O module supports all the position operations supported by the terminal I/O 
module specified in the attach description. 
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Name: signal io 

The signal_io_ I/O module signals a condition whenever an iox_ I/O operation is 
performed. The condition has an info structure that allows a handler of the condition 
to either abort the operation or complete it by setting values in the structure and 
restarting the condition signal. When the condition is restarted, the signal_io_ I/O 
module returns control to the caller of iox_ and returns the output data in the 
structure as corresponding parameters of the iox_ call. 

Applications using this I/O module must have a handler on the stack at all times to 
handle the signal_io_ condition. 

ATTACH DESCRIPTION 

s i gnal_i o_ 

OPEN OPERATION 

All opening modes are supported. 

I/O OPERATIONS (get_chars, get_line, put_chars, read_record, rewrite_record, 
delete_record, read_length, position, seek_key, read_key, write_record, control, modes) 

All operations are supported in appropriate opening modes. See NOTES for a 
discussion of handing the condition associated with these operations. 

NOTES 

When this module is called through iox_ to perform an I/O operation as listed above, 
it signals the "signal_io_" condition with an info structure given here. The condition 
is restartable. 

Applications using this module must establish a handler for the condition that calls 
find_condition_info_ to locate the info structure. If the condition is not handled, the 
default_error_handler_ will print a default error message, unless the condition is 
associated with user_i/o, user_output, user_input or error_output. For these I/O 
switches, terminates the process. 

The returned_error_code in signal_io_info is initially set to 
error_table_$action_not_performed, so if the condition is restarted without first having 
the structure filled in, the iox_ call will return error_table_$action_not_performed. 

This condition does NOT pass through the condition walls established when for new 
command levels. If the application is attaching, for example, user_i/o via this module, 
it must establish a command level intermediary procedure (via cu_$set_cl_intermediary) 
that establishes a new handler for the signal_io_ condition before calling the standard 
intermediary (located via cu_$get_cl_intermediary). 



3-146 



AG93-05 



signal_io_ 



signal_io_ 



For example: 

on signa1_io_ call S I GNAL_I 0_HANDLER; 

call cu_$get_cl_intermediary (std_c l_i ntermed i ary) ; 

call cu_$set__cl_i ntermed i ary (NEW_COMMAND_LEVEL) ; 

{attach/open switch, do work} 

revert signal_io_; 

call cu_$set_cl_i ntermed i ary (std_c l_i ntermed i ary) ; 

NEW_COMMAND_LEVEL: 

procedure (f 1 ags) ; 

del 1 f 1 ags al i gned , 

2 reset_sw bit (1) unaligned, 

3 pad bit (35) unaligned; 

on signal_io_ call S I GNAL_I 0_HANDLER; 

call std_c l_i ntermed i ary (flags); 
return; 

end NEW_COMMAND_LEVEL; 



INFO STRUCTURE 



declare s i gna l_i o_i nf o_ptr 
declare 1 s i gna l_i o_i nf o 
2 header 
2 iocb_name 
2 iocb_ptr 
2 operation 
2 control_order_i nf o 
2 pos i t i on_type 
2 pos i t i on_amount 
2 data_ptr 
2 data_length 
2 returned_data__l ength 
2 returned_error_code 
2 old_modes 

3 pointer 

3 length 
2 new_modes 

3 pointer 

3 length 
2 key 



po i nter ; 
al i gned, 

aligned like cond i t i on_i nf o_header , 
char (32) unal i gned , 
poi nter , 
char (32) , 
ptr pointer, 

f i xed bin, 
fixed bin (35) , 
poi nter , 
fixed bin (21) , 
f i xed bin (21), 
f i xed bin (35) » 
al i gned, 
poi nter , 
f i xed bin (21), 
al i gned, 
poi nter , 
fixed bin (21) , 
char (256) varying; 



deel are 



( 
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SG ! 


OP GET LINE 


i n 


t 


("get_l ine") , 


SGI 


~OP~GET~CHARS 


i n i 


t 


("get_chars") , 


SGI 


_OP_PUT_CHARS 


i ni 


t 


("put_chars") , 


SGI 


OP MODES 


i ni 


t 


("modes") , 


SGI 


OP POSITION 


in' 


t 


("pos i t i on") , 


SGI 


OP CONTROL 


i n 


t 


("control ") , 


SGI 


OP READ RECORD 


i ni 


t 


("read_record") , 


SGI 


OP WRITE RECORD 


in' 


t 


("wr i te_record") , 


SGI 


OP REWRITE RECORD 


i n 


t 


("rewr i te_record") , 


SGI 


OP DELETE RECORD 


in' 


t 


("del ete_record") , 


SGI 


OP SEEK KEY 


in' 


t 


("seek key") , 


SGI 


OP READ KEY 


i n 


t 


("read_key") , 


SGI 


OP READ LENGTH 


i n 


t 


("read_l ength") 



) 

char (32) int static options (constant); 

declare s i gna l_i o_i o_buf f er 

char (s i gnal_i o_i nfo.data_l ength) based (signal_io_info.data_ptr) ; 
declare s i gnal_i o_order_name 

char (s ignal_io_i nf o.data_l ength) based (s i gna l_i o_i nf o.data_ptr) ; 
declare signal_io_old_modes 

char (signal_io_i nf o.old_modes . length) 

based (s i gna l_i o_i nf o .ol d_modes . poi nter) ; 
declare s i gna l_i o_new_modes 

char (s i gna l_i o_i nf o. new_modes . 1 ength) 

based (s i gna l_i o_i nf o . new modes .poi nter) ; 



ARGUMENTS 
header 

is the standard structure declared in condition_info_header.incl.pll. The current 

version is zero. No fields here should be changed by handlers. 

iocb_name 

is the name of the switch. This allows multiple switches to be serviced by the 
same handler. This field should not be changed by a handler. 

iocb_ptr 

is the IOCB pointer for the switch. This allows multiple switches to be serviced 
by the same handler. This field should not be changed by a handler. 

operation 

is the name of the IOX operation that caused this signal. This will be one of the 
the named constants SGI_OP_* declared in signal_io_info.incl.pll. This should not 
be changed by handlers. 

control_order_inf o_ptr 

is the info pointer associated with control orders. For operations other than 
control, this pointer is null. This should not be changed by handlers. 
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position_type 

is the type of position requested in a position operation. This should not be 
changed by handlers. 

position_amount 

is the position distance requested in a position operation. This should not be 
changed by handlers. 

data_ptr 

is a pointer to data to be written on a write operation, or a pointer to a data 
buffer to be filled on a read operation. In a control operation, this points to the 
character string name of the control order. This should not be changed by 
handlers. On read operations, the buffer pointer to by this pointer may be filled 
in. 

data_length 

is the length of the data buffer in nine-bit characters. It should be used 
correspondingly to data_ptr. 

returned_data_length 

is the amount of data read, or found in a record. On get_chars or get_line or 
read_record operations, the handler should set this to the amount of data placed 
in the buffer. On read_length or seek_key or read_key operations, the length of 
the record should be put here. 

returned_error_code 

is the error code to be returned to the caller of iox_. 

old_modes 

is a substructure. It describes a character string that should be set, in a modes 
operation, to the old modes. The pointer and length should not be changed by 
the handler. 

new_modes 

is a substructure. It describes a character string that will be set, in a modes 
operation, to the desired new modes. The pointer and length should not be 
changed by the handler. 

key 

is a keyed record key. On seek_key operations, this will be set to the desired 
key. On read_key operations this should be set by the handler to the key to be 
returned. 
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Name: syn. 



This I/O module may be used to attach an I/O switch, x, as a synonym for another 
switch, y. Thereafter, performing an operation other than attach or detach on x has 
the same effect as performing it on y. There is one exception: if the attach 
description specifies that an operation on y is to be inhibited, performing that 
operation on x results in an error code. 

Entry points in the module are not called directly by users: rather the module is 
accessed through the I/O system. See the Programmer's Reference Manual for a 
general description of the input/output system and a discussion of synonym 
attachments. 

ATTACH DESCRIPTION 

syn_ switch_name {-control_arg} 
ARGUMENTS 
switch_name 

is the name of the I/O switch, y, for which the attached switch, x, is to be a 
synonym. 

CONTROL ARGUMENTS 

-inhibit names, -inn names 

specifies which I/O operations are to be inhibited. The name arguments are 
separated by spaces and must be chosen from the following: 



SWITCH OPERATION 

The detach operation detaches the switch x (the switch attached via syn_). It has no 
effect on the switch y for which x is a synonym. 

INHIBITED OPERATIONS 

An inhibited operation returns the code error_table_$no_operation. 



open 

get_line 

get_chars 

read_record 

rewrite_record 

read_length 

seek_key 

control 



close 

put_chars 

write_record 

delete_record 

position 

read_key 

modes 
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Name: tape„ansi„ 

The tape_ansi_ I/O module implements the processing of magnetic tape files according 
to the American National Standards institute's ANSI X3.27- 7978, "Magnetic Tape 
Labels and File Structure for Information Interchange". This document is referred to 
below as "the Standard". In addition, the I/O module provides a number of features 
that are extensions to, but outside of, the Standard. Using these features may produce 
a nonstandard file, unsuitable for interchange purposes. 

Entries in the module are not called directly by users; rather, the module is accessed 
through the I/O system. See the Programmer's Reference Manual for a general 
description of the I/O system. 

DEFINITION OF TERMS 

For the purpose of this document, the following terms have the meanings indicated. 
They represent a simplification and combination of the exact and complete set of 
definitions found in the Standard. 

record 

related information treated as a unit of information, 
block 

a collection of characters written or read as a unit. A block may contain one or 
more complete records, or it may contain parts of one or more records. A part 
of a record is a record segment A block does not contain multiple segments of 
the same record. 

file 

a collection of information consisting of records pertaining to a single subject. A 
file may be recorded on all or part of a volume, or on more than one volume. 

volume 

a reel of magnetic tape. A volume may contain one or more complete files, or it 
may contain sections of one or more files. A volume does not contain multiple 
sections of the same file. 

file set 

a collection of one or more related files, recorded consecutively on a volume set. 
volume set 

a collection of one or more volumes on which one and only one file set is 
recorded. 

ATTACH DESCRIPTION 

tape_ansi_ vnl vn2 ... vnN {-control_args} 
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ARGUMENTS 
vni 

is a volume specification. A maximum of 64 volumes may be specified. In the 
simplest (and typical) case, a volume specification is a volume name, that must be 
six characters or less in length. If a volume name is less than six characters and 
entirely numeric, it is padded on the left with O's. If a volume name is less than 
six characters and not entirely numeric, it is padded on the right with blanks. 
Occasionally, keywords must be used with the volume name. For a discussion of 
volume names and keywords see "Volume Specification" below. 

vni vn2 ... vnN 

comprise the volume sequence list. The volume sequence list may be divided into 
two parts. The first part, vni ... vni, consists of those volumes that are actually 
members of the volume set, listed in the order that they became members. The 
entire volume set membership need not be specified in the attach description; 
however, the first (or only) volume set member MUST be specified, because its 
volume name is used to identify the file set If the entire membership is 
specified, the sequence list may contain a second part, vni+1 „, vn_N ; consisting of 
potential members of the volume set, listed in the order that they may become 
members. These volumes are known as volume set candidates. (See "Volume 
Switching" below.) 

CONTROL ARGUMENTS 

-block B, -bk B 

specifies the block length in characters, where the value of B is dependent upon 
the value of R specified in the -record control argument. (See "Creating a File" 
below.) 

-clear, -cl 

specifies that internal information on a file-set which the I/O module retains 
from previous attachments is to be deleted. This control argument can be used 
when it is desired to change attributes of a file-set which are maintained across 
attachments for a given process, e.g. density or label standard. For the initial 
attachment to a file-set in a given process, this control argument has no effect. 

-create, -cr 

specifies that a new file is to be created. (See "Creating a File" below.) 
-density N, -den N 

specifies the density at which the file-set is recorded, where N can be 800, 1600, 
or 6250 bits per inch. (See "File Set Density" below.) 

-device N, -dv N 

specifies the maximum number of tape drives that can be used during an 
attachment, where N is an integer in the range 1 <= N <= 63. (See "Multiple 
Devices" below.) 
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-expires date, -exp date 

specifies the expiration date of the file to be created or generated, where date 

must be of a form acceptable to the convert_date_to_binary_ subroutine. (See 
"File Expiration" below.) 

-extend, -ext 

specifies extension of an existing file. (See "Extending a File" below.) 
-force, -fc 

specifies that the expiration date of the file being overwritten is to be ignored. 
(See "File Expiration" below.) 

-format F, -fmt F 

specifies the record format, where F is a format code. (See "Creating a File" 
below for a list of format codes.) 

-generate, -gen 

specifies generation of an existing file. (See "Generating a File" below.) 

-mode STR, -md STR 

specifies the encoding mode used to record the file data, where STR is the string 
ascii, ebcdic, or binary. The default is ascii. (See "Encoding Mode" below.) 

-modify, -mod 

specifies modification of an existing file. (See "Modifying a File" below.) 

-name STR, -nm STR 

specifies the file identifier of the file where STR is from 1 to 17 characters. 
(See "Creating a File" below.) 

-number N, -nb N 

specifies the file sequence number, the position of the file within the file set, 
where N is an integer in the range 1 <= N <= 9999. (See "Creating a File" 
below.) 

-record R, -rec R 

specifies the record length in characters, where the value of R is dependent upon 
the choice of record format. (See "Creating a File" below.) 

-replace STR, -rpl STR 

specifies the file identifier of the file to be replaced, where STR must be from 1 
to 17 characters. If no file with file identifier STR exists, an error is indicated. 
(See "Creating a File" below.) 

-retain STR, -ret STR 

specifies retention of resources across attachments, where STR specifies the 
detach-time resource disposition. (See "Resource Disposition" below.) 
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-ring, -rg 

specifies that the volume set be mounted with write rings. (See "Write Rings and 
Write Protection" below.) 

-speed S1{,S2,...,SN}, -ips SI {,S2 SN] 

specifies desired tape drive speeds in inches per second, where Si can be 75, 125, 
or 200 inches per second. (See "Device Speed Specification" below.) 

The following sections define each control argument in the contexts that it can be 
used. For a complete list of the attach control arguments, see "Attach Control 
Arguments" below. 

CREATING A FILE 

When a file is created, an entirely new entity is added to the file set. There are two 
modes of creation: append and replace. In append mode, the new file is added to the 
file set immediately following the last (or only) file in the set. The process of 
appending does not alter the previous contents of the file set. In replace mode, the 
new file is added by replacing (overwriting) an existing file. The replacement process 
logically truncates the file set at the point of replacement, destroying all files (if any) 
j that follow consecutively from that point 

I The -create and -name control arguments are required to create a file, where STR is 
I the file identifier. No two files in a file set can have the same file identifier. If the 
I act of creation would cause a duplication, an error is indicated. 

I If no file having file identifier STR exists in the file set, the new file is appended to 
I the file set; otherwise, the new file replaces the old file of the same name. 

I If the user wishes to explicitly specify creation by replacement, the particular file to 
j be replaced must be identified. Associated with every file is a name (file identifier) 
j and a number (file sequence number.) Either is sufficient to uniquely identify a 
particular file in the file set The -number N and -replace STR control arguments, 
either separately or in conjunction, are used to specify the file to be replaced. If 
used together, they must both identify the same file; otherwise, an error is indicated. 

When the -number N control argument is specified, if N is less than or equal to the 
sequence number of the last file in the file set, the created file replaces the file 
having sequence number N. If N is one greater than the sequence number of the last 
file in the file set, the created file is appended to the file set If N is any other 
value, an error is indicated. When creating the first file of an entirely new file set, 
the -number 1 control argument must be explicitly specified. (See "Volume 
Initialization" below.) 

The -format F, -record R and -block B control arguments are used to specify the 
internal structure of the file to be created. They are collectively known as structure 
attribute control arguments. 
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When the -format F control argument is used, F must be one of the following 
format codes, chosen according to the nature of the data to be recorded. (For a 
detailed description of the various record formats, see "Record Formats" below.) 

fb for fixed-length records, blocked. 

Used when every record has the same length, not in excess of 99996 characters. 

db for variable length records, blocked. 

Used when records are of varying lengths, the longest not in excess of 99992 
characters. 

sb for spanned records, blocked. 

Used when the record length is fixed and in excess of 99996 characters, or 
variable and in excess of 99992 characters. In either case, the record length 
cannot exceed 1,044,480 characters. 



f for fixed-length records, unblocked, 
d for variable-length records, unblocked, 
s for spanned records, unblocked. 



u for undefined records. 

(records undefined in format). Each block is treated as a single record, and a 
block may contain a maximum of 99996 characters. 

NOTE: THE USE OF UNDEFINED RECORDS IS A NONSTANDARD FEATURE. 

Records recorded using U format may be irreversibly modified; therefore, the use 
of U format is strongly discouraged. (See "Block Padding" below.) 

Unblocked means that each block contains only one record (f, d) or record segment 
(s). Blocked means that each block contains as many records (fb, db) or record 
segments (sb) as possible. The actual number of records/block is either fixed (fb), 
depending upon the block length and record length, or variable (db, sb), depending 
upon the block length, record length, and actual records. Because of their relative 
inefficiency, the use of unblocked formats is discouraged. 

When the -record R control argument is used, the value of R is dependent upon the 
choice of record format. In the following list, amrl is the actual or maximum record 
length. 



F 


= fb 


f : 


R = amrl 


F 


= db 


d: 


amrl + k <- R <= 93396 


F 


= sb 


s: 


amrl <= R <= 10ltM»80 - 


F 


= u: 




R is undefined 



(the -record control argument should not be used.) 
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When the -block B control argument is used, the value of B is dependent upon the 
value of R. When the block length is not constrained to a particular value, the largest 
possible block length should be used. 

F = fb: B must satisfy mod (B,R) = 0 

F = f: B = R 

F = db: B >= R 

F = d: B = R 

F = sb | s: 18 <= B <= 99996 

F - u: amrl <= B <= 99996 



In every case, B must be an integer in the range 18 <= B <= 99996. 

NOTE: THE USE OF A BLOCK LENGTH IN EXCESS OF 2048 CHARACTERS 
IS A NONSTANDARD FEATURE. 



Because the structure attribute control arguments are extremely interdependent, care 
must be taken to ensure that specified values are consistent. 



READING A FILE 



The attach description needed to read a file is less complex than the description used 
to create it When a file is created, the structure attributes specified in the attach 
description are recorded in the file's header and trailer labels. These labels, which 
precede and follow each file section, also contain the file name, sequence number, 
block count, etc. When a file is subsequently read, all this information is extracted 
from the labels. Therefore, the attach description need only identify the file to be 
read; no other control arguments are necessary. 

The file can be identified using the -name STR control argument, the -number N 
control argument, or both in combination. If the -name STR is used, a file with the 
specified file identifier must exist in the file set; otherwise, an error is indicated. If 
the -number control argument is used, a file with the specified file sequence number 
must exist in the file set; otherwise, an error is indicated. If the -name STR and 
-number N control arguments are used together, they must both refer to the same 
file; otherwise, an error is indicated. 



OUTPUT OPERATIONS ON EXISTING FILES 



Three output operations can be performed on an already existing file: extension, 
modification, and generation. As their functions are significantly different, they are 
described separately below. They do, however, share a common characteristic. Like the 
replace mode of creation, an output operation on an existing file logically truncates 
the file set at the point of operation, destroying all files (if any) that follow 
consecutively from that point 



EXTENDING A FILE 



File extension is the process of adding records to a file without in any way altering 
the previous contents of the file. 
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Because all the information regarding structure, length, etc. can be obtained from the 
file labels, the attach description need only specify that an extend operation is to be 
performed on a particular file. The previous contents of the file remain unchanged; 
new data records are appended at the end of the file. If the file to be extended does 
not exist, an error is indicated. 

The file to be extended is identified using the -name STR control argument, the 
-number N control argument, or both in combination. The same rules apply as for 
reading a file. (See "Reading a File" above.) 

Recorded in the labels that bracket every file section is a version number, initially set 
to 0 when the file is created. The version number is used to differentiate between 
data that have been produced by repeated processing operations (such as extension). 
Every time a file is extended, the version number in its trailer labels is incremented 
by 1. When the version number reaches 99, the next increment resets it to 0. 

The user may specify any or all of the structure attribute control arguments when 
extending a file. The specified control arguments are compared with their recorded 
counterparts; if a discrepancy is found, an error is indicated. 

MODIFYING A FILE 

It is occasionally necessary to replace the entire contents of a file, while retaining the 
structure of the file itself (as recorded in the header labels). This process is known as 
modification. 

Because all necessary information can be obtained from the file labels, the attach 
description need only specify that a modify operation is to be performed on a 
particular file. If a file to be modified does not exist, an error is indicated. The 
entire contents of the file are replaced by the new data records. The version number 
in the trailer labels of a modified file is incremented by 1, as described above. 

The file to be modified is identified using the -name STR control argument, the 
-number N control argument, or both in combination. The same rules apply as for 
reading a file. (See "Reading a File" above.) 

If any or all of the structure attribute control arguments are specified, they must 
match their recorded counterparts; otherwise, an error is indicated. 

GENERATING A FILE 

Recorded in the labels that bracket every file section is a generation number, initially 
set to 0 when the file is created. The generation number is used to differentiate 
between different issues (generations) of a file, that all have the same file identifier. 
The duplicate file identifier rule (see "Creating a File" above) precludes multiple 
generations of a file from existing simultaneously in the same file set. 
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The generation number is a higher order of differentiation than the version number, 
that is more correctly known as the generation version number. While the process of 
modification or extension does not change the generation number, the process of 
generation increments the generation number by 1, and resets the version number to 0. 
The generation number can only be incremented by rewriting the header labels, and it 
is in this respect that the processes of generation and modification differ. 

Producing a new generation of a file is essentially the same as creating a new file in 
place of the old; however, the file identifier, sequence number, and structure attributes 
are carried over from the old generation to the new. The attach description need only 
specify that a generation operation is to be performed on a particular file. If the file 
to be generated does not exist, an error is indicated. An entirely new generation of 
the file is created, replacing (and destroying) the previous generation. The generation 
number is incremented by 1; the version number is reset to 0. When the generation 
number reaches 9999, the next increment resets it to 0. 

The file to be generated is identified by the -name STR control argument, the 
-number N control argument, or both in combination. The same rules apply as for 
reading a file. (See "Reading a File" above.) 

If any or all of the structure attribute control arguments are specified, they must 
match those recorded in the labels of the previous generation; otherwise, an error is 
indicated. 

ENCODING MODE 

The tape_ansi_ I/O module makes provision for three data encoding modes: ASCII, 
EBCDIC, and binary. Because the DPSR requires that the data in each record be 
recorded using only ASCII characters, the default data encoding mode is ASCII. File 
labels are always recorded using the ASCII character set. 

When a file is created, the -mode STR can be used to explicitly specify the encoding 
mode, where STR is the string ascii, ebcdic, or binary. The default is the string ascii. 
(If -mode STR is not specified, the list_tape_contents command does not supply the 
specific mode in its report.) 

NOTE: THE USE OF ENCODING MODES OTHER THAN ASCII IS A NONSTANDARD 
FEATURE. 

If STR is the string ascii, the octal values of the characters to be recorded should be 
in the range 000 <- octal_value <= 177; characters in the range 200 to 377 are not 
invalid, but recording such characters is a nonstandard feature; characters in the range 
400 to 777 cause an unrecoverable I/O error. If STR is the string ebcdic, the octal 
values of the characters to be recorded MUST be in the range 000 to 177. (See the 
ascii_to_ebcdic_ subroutine for the specific ASCII to EBCDIC mapping used by the 
I/O module.) If STR is the string binary, any octal value can be recorded. 
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The tape_ansi_ I/O module records the data encoding mode in a portion of the file 
labels reserved for system-defined use. If the -mode STR control argument is 
specified when the file is subsequently extended, modified, or generated, the specified 
mode must match that recorded in the file labels; otherwise, an error is indicated. 
When the file is subsequently read, the encoding mode is extracted from the file 
labels, so the -mode STR control argument need not be specified. 

FILE EXPIRATION 

Associated with every file is a file expiration date, recorded in the file labels. If a 
file consists of more than one file section, the same date is recorded in the labels of 
every section. A file is regarded as "expired" on a day whose date is later than or 
equal to the expiration date. Only when this condition is satisfied can the file (and 
by implication, the remainder of the file set) be overwritten. Extension, modification, 
generation, and the replace mode of creation are all considered to be overwrite 
operations. 

The expiration date is recorded in Julian form; i.e., yyddd, where yy are the last two 
digits of the year, and ddd is the day of the year expressed as an integer in the 
range 1 <= ddd <= 366. A special case of the Julian date form is the value "00000" 
(always expired). 

The expiration date is set only when a file is created or generated. Unless a specific 
date is provided, the default value "00000" is used. The -expires date control argument 
is used to specify an expiration date, where date must be of a form acceptable to the 
convert_date_to_binary_ subroutine; the date may be quoted and contain embedded 
spaces; Julian form, including "00000", is unacceptable. Because overwriting a file 
logically truncates the file set at the point of overwriting, the expiration date of a file 
must be earlier than or equal to the expiration date of the previous file (if any); 
otherwise, an error is indicated. 

If an attempt is made to overwrite an unexpired file, the user is queried for explicit 
permission. (See "Queries" below). The -force control argument unconditionally grants 
permission to overwrite a file without querying the user, regardless of "unexpired" 
status. 

VOLUME SPECIFICATION 

The volume name (also called the slot identifier) is an identifier physically written on, 
or affixed to, the volume's reel or container. The volume identifier is a six-character 
identifier magnetically recorded in the first block of the volume, the VOL1 label. 
This implementation of the I/O module assumes the volume name and volume 
identifier to be identical. If this is not the case, the volume identifier must be used 
in the volume specification field of the attach description. 

If a volume name begins with a hyphen (-), the -volume keyword must precede the 
volume name. Even if the volume name does not begin with a hyphen, it may still be 
preceded by the keyword. The volume specification has the following form: 

-volume vni 
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If the user attempts to specify a volume name beginning with a hyphen without 
specifying the -volume keyword, an error is indicated or the volume name may be 
interpreted as a control argument 

Occasionally, it is necessary for a user to communicate some additional information to 
the operator in connection with a mount request This can be done through the use 
of the -comment control argument 

vni -comment STR 

or: 

-volume vni -comment STR 

where the -comment STR keyword and text specify that a given message is to be 
displayed on the operator's console whenever volume vni is mounted (a comment can 
be specified after each volume name supplied). STR can be from 1 to 64 characters. 
STR can be quoted and contain embedded spaces. 

VOLUME SWITCHING 

The DPSR defines four types of file set configurations: 

single-volume file a single file residing on a single volume, 

multivolume file a single file residing on multiple volumes, 

multifile volume multiple files residing on a single volume, 

multifile multivolume multiple files residing on multiple volumes. 

The tape_ansi_ I/O module maintains a volume sequence list on a per-file-set. basis, 
for the life of a process. A minimal volume sequence list contains only one volume, 
the first (or only) volume set member. If the file set is a multivolume configuration, 
the sequence list may contain one or more of the additional volume set members, 
following the mandatory first volume. If the sequence list contains the entire volume 
set membership (that may be only one volume), it may then contain one or more 
volume set candidates. Volume set candidates can become volume set members only as 
the result of an output operation. When an output operation causes the amount of 
data in the file set to exceed the capacity of the current volume set membership, the 
first available volume set candidate becomes a volume set member. 
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When the first attachment to any file in a file set is made, the volume sequence list 
for the file set is initialized from the attach description. At detach time, the I/O 
module empirically determines that one or more volumes are volume set members, by 
virtue of having used them in the course of processing the attached file. The 
remaining volumes in the sequence list, if any, are considered to be candidates. In 
subsequent attachments to any file in the file set, the order of volumes specified in 
the attach description is compared with the sequence list For those volumes that the 
I/O module knows to be volume set members, the orders must match; otherwise, an 
error is indicated. Those volumes in the sequence list that the I/O module considers 
to be candidates are replaced by attach description specifications, if the orders differ. 
If the attach description contains more volumes than the sequence list, the additional 
volumes are appended to the list. This implementation maintains and validates the 
volume set membership on a per-process basis, and maintains a list of volume set 
candidates that is alterable on a per-attach basis. 

Once a volume sequence list exists, subsequent attachments to files in the file set do 
not require repeated specification of any but the first (or only) volume, that is used 
to identify the file set. If the I/O module detects physical end of tape in the course 
of an output operation, it prepares to switch to the next volume in the volume set. 
An attempt is made to obtain the volume name from the sequence list, either from 
the sublist of members, or the sublist of candidates. If the list of volume set 
members is exhausted, and the list of candidates is either empty or exhausted, the user 
is queried for permission to terminate processing. If the reply is negative, the I/O 
module queries for the volume name of the next volume, which becomes a volume set 
member and is appended to the volume sequence list. If a volume name is obtained 
by either method, it is recorded in a system-defined file label field at the end of the 
current volume, volume switching occurs, and processing of the file continues. 

If the I/O module reaches end of file section (but not of file) in the course of an 
input operation, it first attempts to obtain the next volume name from the volume 
sequence list. No distinction is made between the member and candidate sublists, 
because a volume that ends with a file section must be followed by the volume that 
contains the next section. If the sequence list is exhausted, the file section's labels are 
examined for a volume name and, if one is found, it is appended to the sequence list 
Should the file labels provide no name, the user is queried, as described above. If 
any of these three methods results in a volume name, volume switching occurs, and 
processing of the file continues. This method of searching allows a specified switching 
sequence to override a sequence recorded in the file labels. 

If the volume set is demounted at detach time, all volume set candidates are purged 
from the volume sequence list 



11/86 



3-154.7 



AG93-05A 



tape_ansi_ 



tape_ansi_ 



| MULTIPLE DEVICES 

I 

If a volume set consists of more than one volume, the -device N control argument 
can be used to control device assignment, where N specifies the maximum number of 
tape drives that can be used during this attachment N is an integer in the range 
1 <= N <- 63. Drives are assigned only on a demand basis, and in no case does the 
number actually assigned exceed the device limit of the process. The default for an 
initial attachment to a file in a file set is N equals 1; the default for a subsequent 
attachment to that (or any other) file in the file set is equal to the previous value of 
N. 

FILE SET DENSITY 

Although the DPSR requires that file sets be recorded at 800 bpi (bits per inch), the 
I/O module makes . provision for three densities: 800, 1600, and 6250 bpi. Every file 
in a file set must be recorded at the same density; otherwise, an error is indicated. 

The -density N control argument is used to explicitly specify the file set density, 
where N specifies the density at which the file set is (to be) recorded. N can be 800, 
1600, 6250 bpi. 

The file set density can only be changed in a subsequent attachment if the volume set 
was demounted by the previous attach. 

In the absence of a -density N control argument, the file set density is determined as 
follows: 

open for input: N - density of VOL1 label 

open for output, creating new file set N - 800 bpi 

open for output, old file set: N - density of VOL1 label 

OPENING 

The opening modes supported are sequential_input and sequential_output An I/O 
switch can be opened and closed any number of times in the course of a single 
attachment. Such a series of openings may be in either or both modes, in any valid 
order. 

All openings during a single attachment are governed by the same attach description. 
The following control arguments, all of which pertain to output operations, are ignored 
when the switch is opened for sequential_input: 

-create -generate 

-expires -modify 

-extend -replace 
-force 
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DEVICE SPEED SPECIFICATION 

The -speed control argument is used to specify acceptable tape device speeds in inches 
per second. The module only attaches a device that matches a speed specified by this 
control argument. If more than one speed is specified, the module attaches a device 
that matches one of the speeds. If more than one device is attached, and more than 
one speed is specified, the devices will not necessarily all be of the same speed. 

RESOURCE DISPOSITION 

The tape_ansi_ I/O module utilizes two types of resources: devices (tape drives) and 
volumes. Once an I/O switch is attached, resources are assigned to the user's process 
on a demand basis. When the I/O switch is detached, the default resource disposition 
unassigns all devices and volumes. 

If several attaches and detaches to a file set are made in a process, repeated 
assignment and unassignment of resources is undesirable. Although the processing time 
required to assign and unassign a device is small, all available devices can be assigned 
to other processes in the interval between one detach and the next attach. While 
volumes are not often "competed" for, mounting and dismounting is both time-consuming 
and expensive. 

The -retain STR control argument is used to specify retention of resources across 
attachments, where STR specifies the detach-time resource disposition. If STR is the 
string all, all devices and volumes remain assigned to the process. If STR is the string 
none, all devices and volumes are unassigned. This is the default retention. 

The I/O module provides a further means for specifying or changing the resource 
disposition subsequent to attachment. If retention of any devices or volumes has been 
specified at or subsequent to attach time using the retention control operation, the 
unassign_resource command cannot be used. Instead, use the retain_none or retention 
-none control operation before detaching the I/O module. (See the retention, 
retain_none, retain_all operations under "Control Operations" below.) 

WRITE RINGS AND WRITE PROTECTION 

Before a volume can be written on, a write ring (an actual plastic ring) must be 
manually inserted into the reel. This can only be done before the volume is mounted 
on a device. When a volume is needed, the I/O module sends the operator a mount 
message that specifies if the volume is to be mounted with or without a ring. 

If the attach description contains any output control argument (-extend, -modify, 
-generate, or -create), volumes are mounted with rings; otherwise, they are mounted 
without rings. When a volume set mounted with rings is opened for sequential_input, 
hardware file protect is used to inhibit any spurious write operations. A volume set 
mounted without rings cannot be opened for sequential_output. 
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However, the following sequence of events is possible. An attach description contains 
none of the output control arguments, but does contain the -retain all control 
arguments. The volume set is mounted without rings. After one or more (or no) 
openings for sequential_input, the I/O switch is detached. The volume set remains 
mounted because of the -retain all control argument. Subsequently, an attach is made 
whose description contains an output control argument, that requires that the volume 
set be mounted with rings. However, as rings can only be inserted in unmounted 
volumes, the entire volume set must be demounted and then remounted. 

This situation can be avoided by using the -ring control argument to specify that the 
volume set be mounted with write rings. If no output control argument is specified in 
conjunction with -ring, the I/O switch cannot be opened for sequential_output 

When a volume set is mounted with write rings and the I/O switch is opened for 
sequential_input, the hardware file protect feature is used to safeguard the file set. 

QUERIES 

Under certain exceptional circumstances, the I/O module queries the user for 
information needed for processing to continue or instructions on how to proceed. 

Querying is performed by the command_query_ subroutine. The user may intercept 
one or more types of query by establishing a handler for the command_question 
condition, that is signalled by the command_query_ subroutine. Alternately, the answer 
command (described in the the Commands manual) can be used to intercept all 
queries. The use of a predetermined "yes" answer to any query causes those actions to 
be performed that attempt to complete an I/O operation without human intervention. 

In the following list of queries, status_code refers to command_question_info.status_code. 
See the Programmer's Reference Manual for information regarding the command_question 
condition and the command_question„info structure. 

status_code = error_table_$file_aborted 

This can occur only when the I/O switch is open for sequential_output The I/O 
module is unable to correctly write file header labels, trailer labels, or tapemarks. 
This type of error invalidates the structure of the entire file set Valid file set 
structure can only be restored by deleting the defective file or file section from 
the file set 

The user is queried for permission to delete the defective file or file section. If 
the response is "yes", the I/O module attempts deletion. The attempt may or may 
not succeed; the user is informed if the attempt fails. If the response is "no", no 
action is taken. The user will probably be unable to subsequently process the file, 
or append files to the file set; however, this choice permits retrieval of the 
defective file with another I/O module. In either case, the I/O switch is closed. 

status_code = error_table_$unexpired_volume 

This can occur only when the I/O switch is open for sequential_output A 
volume must be either reinitialized or overwritten; however, the first file or file 
section on the volume is unexpired. 
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The user is queried for permission to initialize or overwrite the unexpired volume. 
If the response is "yes", the volume is initialized or overwritten and processing 
continues. If the response is "no", further processing cannot continue, and the 
I/O switch is closed. 

status_code = error_table_$uninitialized_voIume 

A volume requires reinitialization or user verification before it can be used to 
perform any I/O. . The I/O module distinguishes among four causes by setting 
command_question_info.query_code as follows: 

query_code = 1 

the first block of the tape is unreadable. The tape is either defective, or 
recorded at an invalid density. This query code can occur only if the I/O 
stream is opened for sequential_output. 

query _code = 2 

the first block of the tape is not a valid ANSI VOL1 label. The tape is not 
formatted as an ANSI volume. This query code can occur only if the I/O 
stream is opened for sequential_output. 

query_code = 3 

the volume identifier recorded in the VOL1 label is incorrect The volume 
identifier does not match the volume name. 

query _code = 4 

the density at which the volume is recorded is incorrect. The volume density 
does not match the specified density. This query code can occur only if the 
I/O stream is opened for sequential_output 

If the I/O stream is opened for sequential_output, the user will be asked whether 
he wants to initialize or re-initialize the volume. If the I/O stream is opened 
for sequential_input, the user will be asked whether he wants to continue 
processing in spite of the discrepancy. If the response is "yes", the volume is 
reinitialized and processing continues. If the response is "no", further processing 
cannot continue, and the I/O switch is closed. 

status_code = error_table_$unexpired_file 

This can occur only when the I/O switch is open for sequential_outpuL A file 
that must be extended, modified, generated, or replaced is unexpired. 

The user is queried for permission to overwrite the unexpired file. If the 
response is "yes", processing continues. If the response is "no", further processing 
cannot continue, and the I/O switch is closed. 

status_code = error_table_$no_next_volume 

This can occur when reading a multi volume file, or when writing a file and 
reaching physical end of tape. The I/O module is unable to determine the name 
of the next volume in the volume set 
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The user is queried for permission to terminate processing. If the response is 
"yes", no further processing is possible. If the I/O switch is open for 
sequential_output, the I/O switch is closed. If the response is "no", the user is 
queried for the volume name of the next volume. (See status_code = 0 below.) 

status_code = 0 

This occurs only when the response to the above query is "no". The user is 
requested to supply the name of the next volume. The response must be a 
volume name six characters or less in length, optionally followed by a mount 
message. Even if the volume name begins with a hyphen, it must NOT be 
preceded by the -volume control argument. If a mount message is to be 
specified, the response takes the following form: 

volume_name -comment STR 

where STR is the mount message and need not be a contiguous string. See 

"Volume Specification" above. This is the only query that does not require a 

"yes" or "no" response. If a preset "yes" is supplied to all queries, this particular 
query never occurs. 

STRUCTURE ATTRIBUTE DEFAULTS 

When a file is created, the I/O module can supply a default value for any or all of 
the file structure attributes. The defaults used are as follows: 

1. record format (the default is F - db) 

2. block length (the default is B - 2048) 

3. record length 

F - u: undefined 
F = fb | f: R = block length 
F = db | d: R = block length 
F = sb | s: R = 1044480 

An injudicious combination of explicit specifications and defaults can result in an 
invalid attribute set For example, if the control argument -record 12000 is specified, 
applying the defaults produces the following: 

-format db -block 2048 -record 12000 

| This attribute set is invalid because, in D format (See "Record Formats" below), the 
| record length must be less than or equal to the block length. 
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PROCESSING INTERCHANGE FILES 

The DPSR makes provision for recording record format, block length, and record 
length in specific fields of the HDR2 file label. In addition, the I/O module records 
the encoding mode in a portion of the HDR2 label reserved for system-defined use. 
Because the DPSR restricts the encoding mode to ASCII, there is no "standard" label 
field reserved for recording encoding mode. Therefore, if a foreign interchange file (a 
file not created by this I/O module) uses an encoding mode other than ASCII, the 
-mode STR control argument must be used to specify the mode. 

File sets are almost always recorded with HDR2 file labels, with the exception of 
those created by "primitive" systems at implementation levels 1 or 2. (See the DPSR 
for a description of the facilities supported at different implementation levels.) It is 
therefore rarely necessary to explicitly specify record format, block length, or record 
length when interchange files are read, extended, modified, or generated. If, however, 
a file does lack HDR2 labels, explicit attribute specification is required; defaults apply 
only to file creation. 

ASCII SUBSET 

The DPSR suggests that the characters that comprise certain alphanumeric label fields 
be limited to a 56-character subset of full ASCII. Furthermore, it is suggested that 
these fields should not contain embedded blanks, nor should they consist entirely of 
blanks. In particular, the user need only consider file identifiers and volume names. 

The 56-character subset includes: 

uppercase letters: ABCDEFGHIJKLMNOPQRSTUVWXYZ 

digits: 0123456789 

special characters: <space> ! "%&'()* + ,- . / : ; < = >? 

These characters were chosen from the center four columns of the code table specified 
in USA Standard Code for Information Interchange, ANSI X3.4-1968, except for 
position 5/15 (the underscore (_) character) and those positions where there is 
provision for alternate graphic representation. 

The limitation to this subset is intended to provide maximum interchangeability and 
consistent printing, especially for international interchange. 

OVERRIDING STRUCTURE ATTRIBUTES 

Normally, the -format F, -block B, and -record R control arguments are not included 
in the attach description of an I/O switch that is opened for sequential_input; the 
structure attributes are extracted from the file labels. However, the I/O module 
permits the recorded structure attributes to be overridden by explicitly specified attach 
description control arguments. Because the apparent structure and characteristics of the 
file can be drastically altered, great care must be taken to ensure that attribute 
overrides do not produce unexpected and unwanted results. 
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If a file has the following recorded attributes: 
-format fb -block 800 -record 80 

an explicit specification of the -format F and -record 800 control arguments causes 
each block of ten 80-character records to be treated as a single 800-character record. 

If a file has the following recorded attributes: 

-format fb -block 800 -record 80 

an explicit specification of the -format F, -block 80, and -record 80 control 
arguments causes the last 720 characters of every block to be discarded. No error is 
indicated, because every block of the file contains at least one 80-character record. 

RECORD FORMATS 

ANSI files are structured in one of three record formats: F, D, or S. In addition, 
the I/O module provides for a fourth format, U. When a file is created, its record 
format should be chosen in accordance with the nature of the data to be recorded. 
For example, data consisting of 80-character card images is most economically recorded 
in F format, fixed-length records. Data consisting of variable length text "lines, such 
as PL/ 1 source code produced by a text editor, is best recorded in D format, 
variable-length records. Data of arbitrary length (that could exceed the maximum 
block size) must be recorded in S format, spanned records, so that a lengthy datum 
can span several blocks. 

F, D, and S format files are either blocked or unblocked, blocked being the normal 
case. Each block of an unblocked file contains just one record, whereas each block of 
a blocked file can contain several records. Blocking can provide a significant savings 
of processing time, because several records are accessed with a single physical tape 
movement. Furthermore, as blocks are separated by distances of blank tape, blocking 
reduces the amount of tape needed to contain a file. 



F Format 

In F format, records are of fixed (and equal) length, and files have an integral 
number (N) of records per block. If the file is unblocked, N is equal to 1 and the 
record length (R) is equal to the block length (B). If the file is blocked, N is greater 
than 1 and B is equal to (R * N). N is known as the blocking factor. 
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For example, if R is equal to 800 and B is equal to 800, then the file is unblocked 
and each block contains just one record. 



data | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



block | 800 | j 800 | | 800 | | 800 | | 800 | | 800 | 



If R is equal to 800 and B is equal to 2400, then the file is blocked, the blocking 
factor is 3, and each block contains three records. 



data | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



block | 800 | 800 | 800 | | 800 | 800 | 800 | 



The ANSI standard for F format records permits recording a short block only when 
the last block of a blocked file contains fewer than N records and there are no more 
records to be written when the file is closed. 

There are two special cases in which a datum is padded out to length R. The first 
case is that of iobl (the iox_$write_record I/O buffer length; i.e., the number of 
characters to be written) equals 0: a record of R blanks is written. When such a 
record is subsequently read, it is interpreted as a record of R blanks, and not as a 
zero-length record. The second case is that of 0 < iobl < R: the record is padded 
on the right with blanks to length R, and the padded record written. When such a 
record is read, the original characters plus the padding are returned. The case of iobl 
greater than R is in error. 

NOTE: THE ANSI STANDARD PROHIBITS RECORDING A FIXED-LENGTH 
RECORD THAT CONSISTS ENTIRELY OF CIRCUMFLEX O CHARACTERS. 



D Format 

In D format, records and therefore blocks may vary in length. Each record is 
preceded by a four-character record control word (RCW) that contains the total 
record length (the length of the data plus the length of the RCW itself). 

D format files have an integral number (n) of records per block. If blocked, R is 
less than or equal to B. For blocked records, the number of records per block varies 
indirectly with the size of the records. 
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If R = B = 804 and the file is unblocked, records of up to 800 characters can be 
written, and each block contains one record. 



data | 375 | | 280 | | 610 | | 800 
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block 
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If R equals 804, B is greater than or equal to 804, and the file is blocked, records of 
up to 800 characters can be written. 



data | 375 | | 280 | | 610 | | 800 
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Each block can contain a maximum of 201 zero-length records (a record written as a 
four-character RCW containing 0004). 



S Format 

In S format, a single record is formatted as one or more record segments. A record 
segment contains either a complete record, the initial portion of a record, a medial 
portion of a record, or the final portion of a record. No two segments of the same 
record can be contained in the same block, but a block may contain the segments of 
several different records. The maximum record length is limited only by the maximum 
size of a storage system segment, currently 1,044,480 characters. 

S format files have an integral number of record segments per block. If the file is 
unblocked, each block contains only one record segment; if blocked, the number of 
record segments per block is variable. In either case, R and B are independent of one 
another. 

Each record segment begins with a five-character segment control word (SCW). The 
SCW contains a four-character record segment length, that includes the length of the 
SCW itself. The SCW also contains a one-character record segment code, that indicates 
if the segment contains a complete record, or an initial, medial, or final portion. In 
the examples below, R equals 1000 and B equals 800. 
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U Format 

U format files contain records that do not conform to either F, D, or S format A 
U format file is always unblocked. The record length is undefined, and B is greater 
than or equal to iobl. Blocks may vary in length. 

NOTE: THE USE OF U FORMAT IS A NONSTANDARD FEATURE 

The ANSI block padding convention permits a block (in ANY format) to be padded 
out to any length with circumflex characters ( A ), according to the requirements of the 
system that produces the file. These characters are ignored on input (See "Block 
Padding" below.) In U format, block padding can lead to an ambiguity; i.e., are 
trailing circumflexes indeed pad characters, or are they actually valid data within the 
nonpadded portion of the block. The DPSR suggests that a U format block be treated 
as a single record. In conformance with this suggestion, the I/O module considers 
trailing circumflexes to be valid data. 

The special case of writing a record where iobl is less than 20 characters produces a 
block padded to length 20 with circumflex characters. 
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data | 60 | | 127 | | 16 | | 156 



block J 60 I I 128 I I 20 I I 156 



RECORD FORMAT COMPARISON 

At first glance, it might appear as if S format were the format of choice, simply 
because it has the fewest restrictions and the greatest flexibility. Although the latter is 
certainly true, the former is by no means a valid inference. Increased flexibility is 
almost invariably accompanied by decreased processing efficiency. 

F format requires the least processing time, and should be used if the records are 
fixed-length. If F format is used with nonfixed-length records the record padding 
rules apply, so the user must ensure that recorded data is not irretrievably (and 
perhaps undetectably) modified. 

D format, with explicit inclusion of record length in the RCW, is perhaps the "safest" 
format to use: there are no special padding cases, and the RCW provides an 
additional validity check. The D format processing overhead is small. 

S format permits almost any datum to be recorded, irrespective of length, and further 
has the "safety 1 ' advantage of D format because each segment includes an SCW. While 
S format records provide maximum flexibility, their use entails considerably more 
processing time than the use of F or D format 

BLOCK PADDING 

The DPSR makes provision for extending the recorded length of a block beyond the 
end of the last (or only) record whenever such padding is deemed necessary or 
advisable. Padding characters are not considered when computing an RCW or SCW 
length. Because the Multics system is implemented on a word-oriented computer, the 
number of characters in a block must be evenly divisible by four. The I/O module 
automatically pads every block to the correct length, using from 1 to 3 circumflex 
characters. In addition, the DPSR does not permit recording a block of fewer than 18 
characters. To conform with this requirement, the I/O module pads any block 
containing fewer than 20 characters out to length 20. 

As long as F, D, or S format is used, the presence or absence of block padding 
characters in a particular block is user-transparent. If U format is used, it is the 
responsibility of the user to detect and ignore any pad characters that may be 
generated. 
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VOLUME INITIALIZATION 

The DPSR requires that all volumes be initialized with a VOL1 label and dummy file 
before they are used for output. The I/O module provides a semiautomatic volume 
initialization mechanism that performs this operation as an integral part of the output 
function. The rules that govern permission to initialize a volume are complex, and 
permission to initialize under most circumstances is specifically denied (by the DPSR) 
to the application program. The I/O module's mechanism strikes a balance between 
outright denial and absolute ease. (See "Queries" above.) 

It should be noted that a newly initialized volume contains a dummy file. Thus, if a 
file is created on a newly initialized volume without an explicit specification of the 
-number 1 control argument, the file is appended to the file set, resulting in a file 
sequence number of 2, and not 1 as might be expected. 

BUFFER OFFSET 

The DPSR provides for each block of a file being prefixed by from 1 to 99 
characters of prefix information, known as the buffer offset. The buffer offset length 
is recorded in the HDR2 label. If an input file has block prefixes, and the block 
length is explicitly specified, it must be incremented by the buffer offset length. This 
calculation should made after the block length has been determined using the normal 
block-record relationship rules. 

The I/O module ignores (skips) buffer offsets on input, and does not provide for 
writing buffer offsets on output, except when extending or modifying an interchange 
file with a nonzero buffer offset. In this case, each block written is prefixed with an 
appropriate number of blanks. 

CONFORMANCE TO STANDARD 

The I/O module conforms to the ANSI standard for level 4 implementations with the 
following five exceptions: 

1. Volume Initialization — The I/O module has a permission-granting mechanism 

that can be controlled by the application program. 

2. Volume and File Accessibility — On input, the I/O module always grants 

permission to access. On output, the access control fields in the VOL1 and 
HDR1 labels are always recorded as blank (" "). 

3. Overwriting Unexpired Files — The I/O module has a permission-granting 

mechanism that can be controlled by the application program. 

4. User Label Processing — The I/O module ignores user labels on input, and does 

not provide for writing user labels on output. 

5. Buffer Offset Processing — The I/O module ignores buffer offsets on input, and 

does not provide for writing buffer offsets on output (except as stated above). 
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LABEL PROCESSING 



V0L1 

The label is processed on input and output The owner-identifier field, character 
positions (CP) 38 to 51, holds a three-character volume authentication code. 

UVLa 

These labels are not written on output, and ignored on input 
HDR1/EOF1/EOV1 

The labels are processed on input and output The system-code field, CP 61 to 
73, is recorded as "MULTICS ANSI ". 

HDR2/EOF2/EOV2 

The labels are processed on input and output The reserved-for-system-use field, 
CP 16 to 50, is recorded as follows: 

CP 16 to 47 - full 32-character volume name of next volume (EOV2 only) 
CP 48 - blocking attribute (all) 

"0" = unblocked; "1" * blocked 
CP 49 - data encoding mode (all) 

"1" = ASCII, 9 mode 

"2" = EBCDIC, 9 mode 

"3" = binary 

HDR3/EOF3/EOV3 - HDR9/EOF9/EOV9 

These labels are not written on output and are ignored on input 

UHLa/UTLa 

These labels are not written on output and are ignored on input 
ERROR PROCESSING 

If an error occurs while reading, the I/O module makes 25 attempts to backspace and 
reread. If an error occurs while writing, the I/O module makes 10 attempts to 
backspace, erase, and rewrite. Should an unrecoverable error occur while reading or 
writing the, I/O module "locks" the file so that no further I/O is possible. (See 
reset_error_lock operation below.) If an unrecoverable error occurs while writing file 
labels or tapemarks, the user is queried about preserving the defective file versus file 
set consistency. (See "Queries" above.) If an unrecoverable error occurs during certain 
phases of volume switching or label reading, the I/O switch may be closed. The 
overriding concern of the error recovery strategy is: 

1. to maintain a consistent file set structure. 

2. to ensure the validity of data read or written. 
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CLOSE OPERATION 

The I/O switch must be open. 

CONTROL OPERATION 

The I/O module supports eleven control operations. 

hardware_status retention 

status retain_none 

volume_status retain_all 

file_status reset_error_lock 

feov volume_density 
close_rewind 

In the descriptions below, info_ptr is the information pointer specified in an 
iox_$control entry point call. 



hardware _status Operation 

This operation returns the 72-bit IOM status string generated by the last tape I/O 
operation. The I/O switch must be open. The substr argument (IOM_bits, 3, 10) 
contains the major and minor status codes generated by the tape subsystem itself. (See 
MTS500 Magnetic Tape Subsystem, Order No. DB28, for an explanation of major 
and minor status.) The variable to which info_ptr points is declared as follows: 

declare lOMJaits bit (72) aligned; 



status Operation 

This operation returns a structure that contains an array of status codes, providing an 
interpretation of the IOM status string generated by the last tape I/O operation. 
These codes may be used in calls to the com_err_ subroutine, or may be converted to 
printable strings by calling the convert_status_code_ subroutine. (See the descriptions 
of the com_err_ and convert_status_code_ subroutines.) The I/O switch must be open. 
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The structure to which info_ptr points, device_status.incl.pll, is declared as follows: 

del dstat_ptr pointer; 

del 1 devi ce_status based (dstat_ptr) , 

2 !0M_bits bit (72) aligned, /* I QM status */ 

2 n_minor fixed bin, /* number of minor codes */ 

2 major fixed bin(35)» /* major status code */ 

2 minor (10) fixed bin(35); /* minor status codes */ 



volume_status Operation 

This operation returns a structure that contains the status of the current volume. If 
the I/O switch is open, the current volume is the volume on which the file section 
currently being processed resides. If the switch has never been opened, the current 
volume is the first (or only) volume in the volume set. If the switch was opened, but 
is now closed, the current volume is that on which the last file section processed 
resides. If the switch was closed by the I/O module as the result of an error while 
writing file header labels, trailer labels, or tapemarks, the current volume is the last 
(or only) volume in the volume set. The structure to which info_ptr points, 
tape_volume_status.incl.pll, is declared as follows: 

del tvstat_ptr pointer; 

del 1 tape_vol ume_status based (tvstat_ptr) , 

2 volume_name char (6) , /« volume name */ 

2 volume_id char (6) , /» from V0L1 label */ 

2 volume_seq fixed bin. /* order in volume set */ 

2 tape_drive char (8) , /* tape drive name */ 

/■Si "" if not mounted */ 

2 read_errors fixed bin, /* read error count «/ 

2 write_errors fixed bin; /* write error count */ 

In the current implementation of the I/O module, read_errors and write_errors are 
always zero. Eventually, the resource control package (RCP) supplies these values. 



fi/ejstatus Operation 

This operation returns a structure that contains the current status of the file specified 
in the attach description. If the I/O switch has never been opened, no information 
can be returned; this situation is indicated by tape_file_status. state = 0. If the switch 
was opened, but is now closed, the current status of the file is its status just prior to 
closing. If the switch was closed by the I/O module as the result of an error while 
writing file header labels, trailer labels, or tapemarks, the entire file may have been 
deleted. In this case, the structure contains the current status of the previous file in 
the file set, if any. The structure to which info_ptr points, tape_file_status.incl.pll, is 
declared as follows: 
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del tfstat_ptr pointer; 

del 1 tape_f i 1 e_status based (tf stat_ptr) , 
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The "event" referenced in tape_file_status.state, above, is defined as an error or 
circumstance that prevents continued processing of a file. For example, parity alert 
while reading, reached end of information, no next volume available, etc. 



feov Operation 

This operation forces the end of a volume when writing a file. The switch must be 
open for sequential output. The operation is equivalent to detection of the end of 
tape reflective strip. The info_ptr should be a null pointer. 



close _rew/nd Operation 

This operation specifies that the current volume is to be rewound when the I/O 
switch is next closed. The info_ptr should be a null pointer. The switch need not be 
open when the operation is issued. The operation effects only one close; subsequent 
closings require additional control calls. 
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retention, retain _none, retain _ail Operations 

These operations cause the tape resources currently in use, i.e., tape drives(s) and tape 
volume(s), to be unassigned or retained at detach time according to the specified 
retention argument or operation. The info_ptr points to a fixed binary number with 
value as defined below: 

1 retention -none or retain_none 

causes none of the tape resources currently in use to remain assigned at detach 
time. 

2 retention -volume 

causes the tape volume(s) currently in use to remain assigned at detach time. 

3 retention -device 

causes the tape drives(s) currently in use to remain assigned at detach time. 

4 retention -all or retain_all 

causes all of the devices and volumes currently in use to remain assigned at 
detach time. 



reset _error Jock Operation 

This operation unlocks the files so that further I/O is possible subsequent to a 
parity-type I/O error while reading. Such an error is indicated by a previous 
iox_$read_record or iox_$position call having returned the status code 
error_table_$tape_error. In this case, the value of tape_file_status.event_lock is 
error_table_$tape_error. (See the file_status operation above.) The I/O switch must be 
open for sequential_input. The info_ptr should be a null pointer. 

NOTE: IF RECORDS ARE BLOCKED AND/OR SPANNED, THE VALIDITY OF 
ANY RECORDS READ SUBSEQUENT TO A PARITY-TYPE I/O ERROR IS NOT 
GUARANTEED. (The parity error is reported for the first read of a logical record in 
the block. The actual location of the error in the block is unknown.) 
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voiume_density Operation 

This operation returns the encoded density of the volume set. The I/O switch need 
not be open. The variable to which info_ptr points is declared as follows: 

declare vol ume_dens i ty fixed bin; 
The values returned and their meanings are listed below: 



value meaning 



-1 none specified yet 

2 800 

3 1600 
h 6250 



DETACH OPE RAT I GN 

The I/O switch must be closed. If the I/O module determines that the membership 
of the volume set might have changed, the volume set members are listed before the 
set is demounted; volumes not listed are available for incorporation into other volume 
sets. 

POSITION OPERATION 

The I/O switch must be open for sequential_input. The I/O module does not support 
skipping backwards. In the course of a position operation, events or errors may occur 
that invoke the query mechanism. (See "Queries" above.) An unrecoverable error locks 
the file, and a severe error causes the I/O module to close the I/O switch. 

READ LENGTH OPERATION 

The I/O switch must be open for sequential_input In the course of a read_length 
operation, events or errors may occur that invoke the query mechanism. (See "Queries" 
above.) An unrecoverable error locks the file, and a severe error causes the I/O 
module to close the I/O switch. 

READ RECORD OPERATION 

The I/O switch must be open for sequential_inpuL 

WRITE RECORD OPERATION 

The I/O switch must be open for sequentiaI_output. 
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CONTROL OPERATIONS FROM COMMAND LEVEL 

All control operations supported by this I/O module can be executed from command 
level by using the io_call command. The general format is: 

io_ca11 control switchname operation -control_arg 
ARGUMENTS 
switchname 

is the name of the I/O switch that is attached through, the I/O module to an 
ANSI tape file-set 

operation 

is any of the control operations previously described and summarized below. 



operation abbreviation control_arg 



status st -all 

hardware_status hst 
reset_error_l ock rel 
f i 1 e_status f st 

vol ume_status vst 

retention ret -none, -volume, 

-devi ce, -al 1 

reta i n_a 1 1 reta 

retain_none retn 
close_rewi nd crw 

feov feov 



CONTROL ARGUMENTS 

are operation control arguments valid only for the retention and the status operations. 
A control argument is required for the retention operation. 

-all 

causes all of the devices and volumes currently in use to remain assigned at 
detach time. 

-device 

causes the tape drives(s) currently in use to remain assigned at detach time, 
-none 

causes none of the tape resources currently in use to remain assigned at detach 
time. 

-volume 

causes the tape volume(s) currently in use to remain assigned at detach time. 
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The -all control argument is optional for the status operation. This control argument 
prints all available tape status information such as the device status, the volume status, 
the file status, and the hardware status. The -all control argument is only for use 
with the status operation through the io_call command. It is not defined for use in 
the status operation with iox_$control directly. 

EXAMPLES 

In the following examples, it must be emphasized that an attach description describes a 
potential operation, and in and of itself does nothing to the file. Depending upon the 
sequence of openings in various modes, one attach description can perform diverse 
functions. 

tape_ansi_ 042381 -nm ARD21 -cr -fmt sb -ret all 

A file named ARD21 is to be appended to the file set whose first volume is 042381. 
If a file named ARD21 already exists in the file set, openings for sequential_input 
access that file, and openings for sequential_output create new files replacing the old. 
If no file named ARD21 already exists in the file set, openings for sequential_input 
prior to the first opening for sequential_output fail. The first opening for 
sequential_output creates the file by appending it to the end of the file set. 
Subsequent openings for sequential_input access the newly created file, and subsequent 
openings for sequential_output replace it Spanned records are specified; the block 
length defaults to 2048, the record length to 1044480, and the encoding mode to 
ASCII. The density defaults to 800 bpi, and the maximum number of devices defaults 
to 1. The volume set and devices are retained after detachment. 

tape_ansi_ 042381 -nm fargo.pl 1 -nb 2 -cr -force 
-fmt fb -bk 800 -rec 80 

A file named fargo.pll is created at position 2 in the file set. If a file named 
fargo.pll already exists at position 2, openings for sequential_input prior to the first 
opening for sequential_output access that file. The first opening for sequential_output 
creates a new file, and subsequent openings for sequential_input access the new file. 
If no file named fargo.pll exists at position 2, openings for sequential_input prior to 
the first opening for sequential_output fail. If a file exists at position 2, it is 
replaced irrespective of its expiration date. 

tape_ansi_ 042381 -nm zbx -rpl zbx -cr -md binary -bk 6000 
-exp 2weeks 
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A file named zbx is to be created, replacing a file of the same name. Openings for 
sequential_input prior to the first opening for sequential_output access the old file. 
Each opening for sequential_output creates a new file, and each subsequent opening 
for sequentiaMnput accesses the most recently created file. The specified encoding 
mode is binary. The record format defaults to D, blocked, and the record length 
defaults to 6000 because the block length is specified as 6000. The file is protected 
from overwriting for a period of two weeks, so each opening for sequential_output 
subsequent to the initial opening for sequential_output causes the user to be queried 
for permission to overwrite. 

tape_ansi_ 042381 -nb 14 -gen -dv 3 -expires 12/31/83 

A new generation of the file at position 14 in the file set is to be created, replacing 
the old generation. If the old generation is not expired, the user is queried for 
permission to overwrite. Each opening for sequentiaMnput accesses the current 
generation. Each opening for sequential_output creates a new generation. The new 
generation has an expiration date of December 31, 1983. The maximum number of 
devices that can be used is three. 

tape_ansi_ 042381 042382 042383 ~nm THESIS -rg 

A file named THESIS is to be read. The I/O switch can only be open for 
sequentiaMnput. The volume set consists of at least three volumes, and they are 
mounted with write rings. Only one device can be used. 

tape_ansi_ 042381 -nm FF -nb 3 -ext -dv 4 -ret all 

A file named FF at position 3 in the file set is to be extended. Each opening for 

sequentiaMnput accesses the current version. Each opening for sequential_output 

produces a new version. A maximum of four devices can be used, and resources are 
retained after detachment. 

tape_ansi_ 042381 -vol -COS -com i n_s lot_000034 -nb 6 -mod -fc 

The file at position 6 in the file set is to be modified, irrespective of its expiration 
date. Each opening for sequentiaMnput accesses the current version. Each opening for 
sequential_output produces a new version. The second volume of the volume set has 
volume identifier -COS, and can be found in slot 000034. 
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ATTACH CONTROL ARGUMENTS 



The following is a complete list of all valid attach control arguments in both long and 
short forms: 



■block B 
■c 1 ear 
■create 
-density N 
■device N 
■expires DATE 
■extend 
■force 
■format F 



•bk B 

•cl 
•cr 

•den N 
■dv N 
•exp DATE 
•ext 
•fc 

-fmt F 



18 <= B <= 99996 



N = 800 I 1600 
1 <= N <= 63 
val id date 



6250 



F = fb 
sb 



db 
u 



« l 



-generate 


-gen 








-mode STR 


-md STR 


STR 


= asci 


i | ebcdic 


-mod i f y 


-mod 








-name STR 


-nm STR 


STR 


<= 17 


characters 


-number N 


_ u 11 


1 — _ 


LI 




— \\u n 


1 ~*->- — 


■ IX ^— 




-record R 


-rec R 


1 <= 


• R <= 




-repl ace 


-rpl 


STR 


<= 17 


characters 


-retain STR 


-ret STR 


STR 


= al 1 


| none 


-r i ng 


-rg 









I binary 



The following is a list of positional keywords: 



-comment STR 
-volume vni 



-com STR STR <= 64 characters 
-vol vni vni <= 6 characters 



Name: tape ibm 

The tape_ibm_ I/O module implements the processing of magnetic tape files in 
accordance with the standards established by the following IBM publications: OS Data 
Management Services Guide, Release 21.7, GC26-3 746-2; iBM System 360 Disk 
Operating System Data Management Concepts, GC24-3427-8; and OS Tape Labels, 
Release 21, GC28-6680-4. These documents are collectively referred to below as the 
Standard. 

Entries in the module are not called directly by users; rather, the module is accessed 
through the I/O system. See the Programmer's Reference Manual for a general 
description of the I/O system. 
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Definition of Terms 



record 

related information treated as a unit of information, 
block 

a collection of characters written or read as a unit. A block may contain one or 
more complete records, or it may contain parts of one or more records. A part 
of a record is a record segment. A block does not contain multiple segments of 
the same record. 

file 

a collection of information consisting of records pertaining to a single subject. A 
file may be recorded on all or part of a volume, or on more than one volume. 

volume 

a reel of magnetic tape. A volume may contain one or more complete files, or it 
may contain sections of one or more files. A volume does not contain multiple 
sections of the same file. 

file set 

a collection of one or more related files, recorded consecutively on a volume set. 
volume set 

a collection of one or more volumes on which one and only one file set is 
recorded. 



Attach Description 

tape_ibm_ vnl vn2 ... vnN {-control_args} 
ARGUMENTS 
vni 

is a volume specification. A maximum of 64 volumes may be specified. In the 
simplest (and typical) case, a volume specification is a volume name that must be 
six characters or less in length. If a volume name is less than six characters and 
entirely numeric, it is padded on the left with O's. If a volume name is less than 
six characters and not entirely numeric, it is padded on the right with blanks. 
Occasionally, keywords must be used with the volume name. For a discussion of 
volume name and keywords see "Volume Specification" below. 
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vnl vn2 ... vnN 

comprise what is known as the volume sequence list. The volume sequence list 
may be divided into two parts. The first part, vnl ... vni, consists of those 
volumes that are actually members of the volume set, listed in the order that they 
became members. The entire volume set membership need not be specified in the 
attach description; however, the first (or only) volume set member MUST be 
specified, because its volume name is used to identify the file set. If the entire 
membership is specified, the sequence list may contain a second part, (vni+1) ... 
vnN, consisting of potential members of the volume set, listed in the order that 
they may become members. These volumes are known as volume set candidates. 
(See "Volume Switching" below.) 

CONTROL ARGUMENTS 

A control argument may appear only once. 

-block B, -bk B 

specifies the block length in characters, where the value of B is dependent upon 
the value of R specified in the -record control argument. (See "Creating A File" 
below.) 

-clear, -cl 

specifies that internal information on a file-set which the I/O module retains 
from previous attachments is to be deleted. This control argument can be used 
when it is desired to change attributes of a file-set which are maintained across 
attachments for a given process, e.g. density or label standard. For the initial 
attachment to a file-set in a given process, this control argument has no effect. 

-create, -cr 

specifies that a new file is to be created. (See "Creating A File" below.) 
-density N, -den N 

specifies the density at which the file set is recorded, where N can be 800, 1600, 
or 6250 bits per inch. (See "File Set Density" below.) 

-device N, -dv N 

specifies the maximum number of tape drives that can be used during an 
attachment, where N is an integer in the range 1 <= N <= 63. (See "Multiple 
Devices" below.) 

-dos 

specifies that a file was produced by, or is destined for, a DOS installation. (See 
"DOS Files" below.) 

-expires date, -exp date 

specifies the expiration date of the file to be created or generated where date 

must be of a form acceptable to the convert_date_to_binary_ subroutine. (See 
"File Expiration" below.) 
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-extend, -ext 

specifies extension of an existing file. (See "Extending a File" below.) 
-force, -fc 

specifies that the expiration date of the file being overwritten is to be ignored. 
(See "File Expiration" below.) 

-format F, -fmt F 

specifies the record format, where F is a format code. (See "Creating A File" 
below for a list of format codes.) 

-mode STR, -md STR 

specifies the encoding mode used to record the file data, where STR is the string 
ebcdic, ascii, or binary; the default is ebcdic. (See "Encoding Mode" below.) 

-modify, -mod 

specifies modification of an existing file. (See "Modifying a File" below.) 

-name STR, -nm STR 

specifies the file identifier of the file, where STR is from 1 to 17 characters. 
(See "Creating A File" below.) 

-nojabels, -nib 

specifies that unlabeled tapes are to be processed. (See "Unlabeled Tapes" below.) 
-number N, -nb N 

specifies the file sequence number, the position of the file within the file set, 
where N is an integer in the range 1 <= N <= 9999. (See "Creating A File" 
below.) 

-record R, -rec R 

specifies the record length in characters, where the value of R is dependent upon 
the choice of record format (See "Creating A File" below.) 

-replace STR, -rpl STR 

specifies the file identifier of the file to be replaced, where STR must be from 1 
to 17 characters. If no file with file identifier STR exists, an error is indicated. 
(See "Creating A File" below.) 

-retain STR, -ret STR 

specifies retention of resources across attachments, where STR specifies the 
detach-time resource disposition. (See "Resource Disposition" below.) 

-ring, -rg 

specifies that the volume set be mounted with write rings. (See "Write Rings and 
Write Protection" below.) 

-speed S1{,S2,...,SN}, -ips SI {, S2, . . . ,SN} 

specifies desired tape drive speeds in inches per second, where Si can be 75, 125, 
or 200 inches per second. (See "Device Speed Specification" below.) 



3-165 



AG93-05 



tape_ibm_ 



tape_ibm_ 



The following sections define each control argument in the contexts in which it can be 
used. For a complete list of the attach control arguments see "Attach Control 
Arguments" below. 



File Identifiers 

Associated with every file is a name (file identifier) and a number (file sequence 
number). The file identifier must be 17 characters or less. When creating a file, the 
file identifier must be composed of one or more components of one to eight 
characters, with adjacent components separated by a period. The first character of 
each component must be an uppercase letter or national character (@, #, or $) and 
the remaining characters must be uppercase letters, national characters or the digits 0 
to 9. If a file identifier (of an existing file) does not meet the naming conventions 
established for files created on the Multics system, the file must be referenced using 
the -number control argument and a file sequence number. 



Creating A File 

When a file is created, an entirely new entity is added to the file set There are two 
modes of creation; append and replace. In append mode, the new file is added to the 
file set immediately following the last (or only) file in the set. The process of 
appending does not alter the previous contents of the file set In replace mode, the 
new file is added by replacing (overwriting) a particular previously existing file. The 
replacement process logically truncates the file set at the point of replacement, 
destroying all files (if any) that follow consecutively from that point. 

The -create and -name control arguments are required to create a file, where STR is 
the file identifier. If no file having file identifier STR exists in the file set, the new 
file is appended to the file set; otherwise, the new file replaces the old file of the 
same name. 

If the user wishes to explicitly specify creation by replacement, the particular file to 
be replaced must be identified. Either a file identifier or a file sequence number is 
sufficient to uniquely identify a particular file in the file set. The -number and 
-replace control arguments either separately or in conjunction, are used to specify the 
file to be replaced. If used together, they must both identify the same file; otherwise, 
an error is indicated. 

When the -number control argument is specified, if N is less than or equal to the 
sequence number of the last file in the file set, the created file replaces the file 
having sequence number N. If N is one greater than the sequence number of the last 
file in the file set, the created file is appended to the file set If N is any other 
value, an error is indicated. When creating the first file of an entirely new file set, 
the -number control argument must be explicitly specified. (See "Volume Initialization" 
below.) 
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The -format, -record and -block control arguments are used to specify the internal 
structure of the file to be created. They are collectively known as structure attribute 
control arguments. When the -format control argument is used, F must be one of the 
following format codes, chosen according to the nature of the data to be recorded. 
(For a detailed description of the various record formats, see "Record Formats" 
below.) 

fb for fixed-length records. 

Used when every record has the same length, not in excess of 32760 characters. 

vb for variable-length records. 

Used when records are of varying lengths, the longest not in excess of 32752 
characters. 



vbs for spanned records. 

Used when the record length is fixed and in excess of 32760 characters, or 

variable and in excess of 32752 characters. In either case, the record length 

cannot exceed 1,044,480 characters. (See "DOS Files" below.) 

f for fixed-length records, unblocked. 

v for variable-length records, unblocked. 

vs for spanned records, unblocked. 
(See "DOS Files" below.) 



NOTE: Because of padding requirements records recorded using vs format may be 
irreversibly modified. (See "Padding" below.) 

Unblocked means that each block contains only one record (f, v) or record segment 
(vs). Because of their relative inefficiency, the use of unblocked formats in general is 
discouraged. Blocked means that each block contains as many records (fb, vb) or 
record segments (vbs) as possible. The actual number of records/ block is either fixed 
(fb), depending upon the block length and record length, or variable (vb, vbs), 
depending upon the block length, record length, and actual records. 

u for undefined records. 

U format records are undefined in format Each block is treated as a single 
record, and a block may contain a maximum of 32760 characters. 

When the -record control argument is used, the value of R is dependent upon the 
choice of record format In the following list, amrl is the actual or maximum record 
length. 

F = fb f: R = amrl 
F = vb v: amrl + k <= R <= 3275& 
F = vbs | vs: amrl <= R <= 10M*i»80 
F = u: R is undefined 

(the -record control argument should not be used.) 
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When the -block control argument is used, the value of B is dependent upon the 
value of R. When the block length is not constrained to a particular value, the largest 
possible block length should be used. 

F = fb: B must satisfy mod (B,R) = 0 

F = f: B = R 

F = vb: b >= R + k 

F * v: • B - R + k 

F = vbs | vs: 20 <= B <= 32760 

F - u: amrl <= B <= 32760 



In every case, B must be an integer in the range 20 <= B <- 32760, and, when the 
I/O switch is opened for sequential_output, must satisfy mod (B,4) = 0. 

Since the structure attribute control arguments are interdependent, care must be taken 
to ensure that specified values are consistent 



Padding 

Since the Multics system is implemented on word oriented hardware, records recorded 
in any format are subject to block and /or record padding. On output, the hardware 
requires that the number of characters in a block be evenly divisible by 4; i.e., only 
words can be written. The I/O module therefore requires that mod (B,4) - 0, and 
pads a record, if necessary, to meet this requirement. (Warning: this padding may 
cause IBM-system rejection of a block if block length is not a multiple of the record 
iength.) The following rules govern padding on output 



F = fb: if iobl (the I/O buffer length in an iox_$write_record call; i.e., the 
number of characters to be written) is less than R, the record is 
padded on the right with blanks to length R. The last (or only) record 
of the file may be padded on the right with N blanks, where 
0 <= N <= 19 is sufficient to satisfy B >= 20, and mod (B,4) = 0. 

F - f: if iobl is less than R, the record is padded on the right with blanks to 

length R. Because the specified value of B must satisfy B >= 20, mod 
(B,4) = 0, and R - B, there are no other padding possibilities. 

F - vb: the last (or only) record in every block is padded on the right with N 
blanks, where 0 <= N <= 12 is sufficient to satisfy B >= 20, and mod 
(B,4) - 0, Because the number of records in a block is variable, it is 
difficult to determine which records of a file are padded, if any. 

F = v: every record is padded on the right with N blanks, where 0 <ss N <■ 12 

is sufficient to satisfy B >- 20, and mod (B,4) = 0. 



F = vbs: the last (or only) record of the file is padded on the right with N 
blanks, where 0 <■ N <= 12 is sufficient to satisfy B >~ 20, and mod 
(B,4) = 0. 
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F = vs: every record or record segment is padded on the right with N blanks, 

where 0 <= N <= 12 is sufficient to satisfy B >= 20, and mod (B,4) = 0. 

NOTE: This requirement can result in an indeterminate number of blanks being 
inserted into a record at one or more indeterminate positions. 

F = u: every record is padded on the right with N blanks, where 0 <- N <- 12 

is sufficient to satisfy B >= 20, and mod (B,4) - 0. 



Reading A File 

The attach description needed to read a file is less complex than the description used 
to create it. When a file is initially created by the I/O module, the structure 
attributes specified in the attach description are recorded in the file's header and 
trailer labels. These labels, that precede and follow each file section, also contain the 
file name, sequence number, block count, etc. Files created by OS installations also 
record the structure attributes in the file labels. (See "DOS Files" below.) When a 
file is subsequently read, all this information is extracted from the labels. Therefore, 
the attach description need only identify the file to be read; no other control 
arguments are necessary. 

The file can be identified using the -name control argument, the -number control 
argument, or both in combination. If the -name control argument is used, a file with 
the specified file identifier must exist in the file set; otherwise, an error is indicated. 
If the -number control argument is used, a file with the specified file sequence 
number must exist in the file set; otherwise, an error is indicated. If the -name and 
-number control arguments are used together, they must both refer to the same file; 
otherwise, an error is indicated. 



DOS Files 

Files created by DOS installations differ from OS files in one major respect — DOS 
does not record HDR2 labels, which contain the structure attributes. It is therefore 
necessary to specify all of the structure attributes whenever a file created by a DOS 
installation is to be processed. 

It is further necessary to distinguish between OS and DOS files recorded in VBS or 
VS format The segment descriptor word (SDW) of a zero-length DOS spanned record 
has a high-order null record segment bit set, while a zero-length OS spanned record 
does not. (See "V(B)S Format" below, for an explanation of the SDW.) 

The -dos control argument must be used when writing a VBS or VS file destined for 
a DOS installation, or when reading a VBS or VS file written by a DOS installation. 
In the interest of clarity, however, it is recommended that the control argument 
always be specified when DOS files are processed, regardless of record format 
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Output Operations On Existing Files 

There are two output operations that can be performed on an already existing file: 
extension and modification. As their functions are significantly different, they are 
described separately below. They do, however, share a common characteristic. Like the 
replace mode of creation, an output operation on an existing file logically truncates 
the file set at the point of operation, destroying all files (if any) that follow 
consecutively from that point Because the block length is constrained to mod(B,4) = 0 
for output operations, a file whose block length does not satisfy this criterion cannot 
be extended or modified. 



Extending A File 

It is often necessary to add records to a file without in any way altering the previous 
contents of the file. This process is known as extension. 

Because all the information regarding structure, length, etc., can be obtained from the 
file labels, the attach description need only specify that an extend operation is to be 
performed on a particular file. (See "DOS Files" above.) If the file to be extended 
does not exist, an error is indicated. New data records are appended at the end of 

j the file; the previous contents of the file remain unchanged. 

The file to be extended is identified using the -name control argument, the -number 
control argument, or both in combination. The same rules apply as for reading a file. 
(See "Reading a File" above.) 

The user may specify any or all of the structure attribute control arguments when 
extending a file. The specified control arguments are compared with their recorded 
counterparts; if a discrepancy is found, an error is indicated. 



Modifying A File 

It is occasionally necessary to replace the entire contents of a file, while retaining the 
structure of the file itself. This process is known as modification. 

Because all necessary information can be obtained from the file labels, the attach 
description need only specify that a modify operation is to be performed on a 
particular file. (See "DOS Files" above.) If a file to be modified does not exist, an 
error is indicated. The entire contents of the file are replaced by the new data 
records. 

The file to be modified is identified using the -name control argument, the -number 
control argument, or both in combination. The same rules apply as for reading a file. 
(See "Reading a File" above.) 

If any or all of the structure attribute control arguments are specified, they must 
match their recorded counterparts; otherwise, an error is indicated. 
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Encoding Mode 

The I/O module makes provision for three data encoding modes: EBCDIC, binary, 
and ASCII. The default data encoding mode is EBCDIC. File labels are always 
recorded using the EBCDIC character set. 

When a file is created, the -mode control argument can be used to explicitly specify 
the encoding mode (if not used, the list_tape_contents command does not supply the 
specific mode in its report). 

If STR is the string ascii, the octal values of the characters to be recorded must be 
in the range 000 <- octal_value <= 377; otherwise, an unrecoverable I/O error occurs. 
If STR is the string ebcdic, the octal values of the characters to be recorded must be 
in the range 000 <■ octal_value <- 177. (See the ascii_to_ebcdic_ subroutine for the 
specific ASCII to EBCDIC mapping used by the I/O module.) If STR is the string 
binary, any 9-bit byte value can be recorded. However, data written on IBM 
equipment with binary mode may not be compatible with Multics, or vice versa. 

Because the data encoding mode is not recorded in the file labels, the -mode ascii 
and the -mode binary control arguments must always be specified when subsequently 
processing an ASCII or binary file, respectively. 



File Expiration 

Associated with every file is a file expiration date, recorded in the file labels. If a 
file consists of more than one file section, the same date is recorded in the labels of 
every section. A file is regarded as "expired" on a day whose date is later than or 
equal to the expiration date. Only when this condition is satisfied can the file (and 
by implication, the remainder of the file set) be overwritten. Extension, modification, 
and the replace mode of creation are all considered to be overwrite operations. 

The expiration date is recorded in Julian form; i.e., yyddd, where yy are the last two 
digits of the year, and ddd is the day of the year expressed as an integer in the 
range 1 <= ddd <= 366. A special case of the Julian date form is the value "00000", 
which means always expired. 

The expiration date is set only when a file is created. Unless a specific date is 
provided, the default value "00000" is used. The -expires control argument is used to 
specify an expiration date where date must be of a form acceptable to the 
convert_date_to_binary_ subroutine; the date may be quoted and contain embedded 
spaces; Julian form, including "00000", is unacceptable. Because overwriting a file 
logically truncates the file set at the point of overwriting, the expiration date of a file 
must be earlier than or equal to the expiration date of the previous file (if any); 
otherwise, an error is indicated. 

If an attempt is made to overwrite an unexpired file, the user is queried for explicit 
permission. (See "Queries" below). The -force control argument unconditionally grants 
permission to overwrite a file without querying the user, regardless of "unexpired" 
status. 
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Volume Specification 

The volume name (aiso caiied the slot identifier) is an identifier physically written on, 
or affixed to, the reel or container of the volume. The volume identifier is a 
six-character identifier magnetically recorded in the first block of the volume, the 
VOL1 label. This implementation of the I/O module assumes the volume name and 
volume identifier to be identical. If this is not the case, the volume identifier must 
be used in the volume specification field of the attach description. 

If a volume name begins with a hyphen (-), the -volume keyword must precede the 
volume name. Even if the volume name does not begin with a hyphen, it may still be 
preceded by the -volume keyword. The volume specification has the following form: 

-volume vni 

If the user attempts to specify a volume name beginning with a hyphen without 
specifying the -volume keyword, an error is indicated or the volume name may be 
interpreted as a control argument. 

Occasionally, it is necessary for a user to communicate some additional information to 
the operator in connection with a mount request This can be done through the use 
of the -comment control argument: 

vni -comment STR 

or : 

-volume vni -comment STR 

where the -comment STR keyword and text specify that a given message is to be 
displayed on the operator's console whenever volume vni is mounted (a comment can 
be specified after each volume name supplied). STR can be from 1 to 64 characters. 
STR can be quoted and contain embedded spaces. 



Volume Switching 

The Standard defines four types of file set configurations: 



single- volume file 
multivolume file 
multifile volume 
multifile multivolume 



a single file residing on a single volume, 
a single file residing on multiple volumes, 
multiple files residing on a single volume, 
multiple files residing on multiple volumes. 



11/86 



3-166.6 



AG93-05A 



tape_ibm_ 



tape_ibm_ 



The I/O module maintains a volume sequence list on a per- file-set basis, for the life 
of a process. A minimal volume sequence list contains only one volume, the first (or 
only) volume set member. If the file set is a multivolume configuration, the sequence 
list may contain one or more of the additional volume set members, following the 
mandatory first volume. If the sequence list contains the entire volume set 
membership (which may be only one volume), it may then contain one or more 
volume set candidates. Volume set candidates can become volume set members only as 
the result of an output operation. When an output operation causes the amount of 
data in the file set to exceed the capacity of the current volume set membership, the 
first available volume set candidate becomes a volume set member. 

When the first attachment to any file in a file set is made, the volume sequence list 
for the file set is initialized from the attach description. At detach time, the I/O 
module empirically determines that one or more volumes are volume set members, by 
virtue of having used them in the course of processing the attached file. The 
remaining volumes in the sequence list, if any, are considered to be candidates. In 
subsequent attachments to any file in the file set, the order of volumes specified in 
the attach description is compared with the sequence list. For those volumes that the 
I/O module knows to be volume set members, the orders must match; otherwise, an 
error is indicated. Those volumes in the sequence list that the I/O module considers 
to be candidates are replaced by attach description specifications, if the orders differ. 
If the attach description contains more volumes than the sequence list, the additional 
volumes are appended to the list. This implementation maintains and validates the 
volume set membership on a per-process basis, and maintains a list of volume set 
candidates that is alterable on a per-attach basis. 

Once a volume sequence list exists, subsequent attachments to files in the file set do 
not require repeated specification of any but the first (or only) volume, which is used 
to identify the file set If the I/O module detects physical end of tape in the course 
of an output operation, it prepares to switch to the next volume in the volume set 
An attempt is made to obtain the volume name from the sequence list, either from 
the sublist of members, or the sublist of candidates. If the list of volume set 
members is exhausted, and the list of candidates is either empty or exhausted, the user 
is queried for permission to terminate processing. If the reply is negative, the I/O 
module queries for the volume name of the next volume, which becomes a volume set 
member and is appended to the volume sequence list If a volume name is obtained 
by either method, volume switching occurs, and processing of the file continues. 

If the I/O module reaches end-of-file section (but not of file) in the course of an 
input operation, it first attempts to obtain the next volume name from the volume 
sequence list. No distinction is made between the member and candidate sublists, 
because a volume that ends with a file section must be followed by the volume that 
contains the next section. If the sequence list is exhausted, the user is queried as 
described above. If either of these methods results in a volume name, volume 
switching occurs and processing of the file continues. 

If the volume set "is demounted at detach time, all volume set candidates are purged 
from the volume sequence list. 
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Multiple Devices 

If a volume set consists of more than one volume, the -device control argument can 
be used to control device assignment, where N specifies the maximum number of tape 
drives that can be used during this attachment (N is an integer in the range 
1 <= N <= 63). Drives are assigned only on a demand basis, and in no case does the 
number actually assigned exceed the device limit of the process. The default for an 
initial attachment to a file in a file set is N equals 1; the default for a subsequent 
attachment to that file or any other in the file set equals the previous value of N. 



File Set Density 

The I/O module makes provision for three densities: 800, 1600, and 6250 bpi (bits per 
inch). Every file in a file set must be recorded at the same density; otherwise, an 
error is indicated. 

The -density control argument is used to explicitly specify the file set density, where 
N specifies the density at which the file set is (to be) recorded (N can be 800, 1600, 
and 6250 bpi). The file set density can only be changed in a subsequent attachment if 
the volume set was demounted by the previous attach. 

In the absence of a -density control argument, the file set density is determined as 
follows: 

open for input: N = density of VOL1 label 

open for output, creating new file set: N = 1600 bpi 

open for output, old file set: N = density of VOL1 label 



Device Speed Specification 

The -speed control argument is used to specify acceptable tape device speeds in inches 
per second. The module only attaches a device that matches a speed specified by this 
control argument. If more than one speed is specified, the module attaches a device 
that matches one of the speeds. If more than one device is attached, and more than 
one speed is specified, the devices will not necessarily all be of the same speed. 



Opening 

The opening modes supported are sequential_input and sequential_output. An I/O 
switch can be opened and closed any number of times in the course of a single 
attachment Such a series of openings may be in either or both modes, in any valid 
order. 

All openings during a single attachment are governed by the same attach description. 
The following control arguments ; all of which pertain to output operations, are ignored 
when the switch is opened for sequential_input: 
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-create 



-force 



-expires -modify 
-extend -replace 



Resource Disposition 

The I/O module utilizes two types of resources: devices (tape drives), and volumes. 
Once an I/O switch is attached, resources are assigned to the user's process on a 
demand basis. When the I/O switch is detached, the default resource disposition 
unassigns all devices and volumes. 

If several attaches and detaches to a file set are made in a process, repeated 
assignment and unassignment of resources is undesirable. Although the processing time 
required to assign and unassign a device is small, all available devices can be assigned 
to other processes in the interval between one detach and the next attach. While 
volumes are not often "competed" for, mounting and demounting is both time-consuming 
and expensive. 

The -retain control argument is used to specify retention of resources across 
attachments, where STR specifies the detach-time resource disposition. If STR is the 
string all, all devices and volumes remain assigned to the process. If STR is the string 
none, all devices and volumes are unassigned. This is the default retention. 

The I/O module provides a further means for specifying or* changing the resource 
disposition subsequent to attachment If retention of any devices or volumes has been 
specified at or subsequent to attach time using the retention control operation, the 
unassign_resource command cannot be used. Instead, use the retain_none or retention 
-none control operation before detaching the I/O module. (See the retention, 
retain_none, retain_all operations under "Control Operations" below.) 



Write Rings And Write Protection 

Before a volume can be written on, a write ring (an actual plastic ring) must be 
manually inserted into the reel. This can only be done before the volume is mounted 
on a device. When a volume is needed, the I/O module sends the operator a mount 
message that specifies if the volume is to be mounted with or without a ring. 

If the attach description contains any of the output control arguments (-extend, 
-modify, or -create), volumes are mounted with rings; otherwise, they are mounted 
without rings. When a volume set mounted with rings is opened for sequentiaLinput, 
hardware file protect is used to inhibit any spurious write opera tions= A volume set 
mounted without rings cannot be opened for sequential_output 
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However, the following sequence of events is possible. An attach description contains 
none of the output control arguments, but does contain the "-retain all" control 
argument. The volume set is mounted without rings. After one or more (or no) 
openings for sequential_input, the I/O switch is detached. The volume set remains 
mounted because of the "-retain all" control argument Subsequently, an attach is 
made whose description contains an output control argument, which requires that the 
volume set be mounted with rings. However, as rings can only be inserted in a 
demounted volume, the entire volume set must be demounted and then remounted. 

This situation can be avoided by using the -ring (-rg) control argument to specify that 
the volume set be mounted with write rings. If no output control argument is 
specified in conjunction with -ring, the I/O switch cannot be opened for sequential_output 

When a volume set is mounted with write rings and the I/O switch is opened for 
sequential_input, the hardware file protect feature is used to safeguard the file set. 



Queries 

Under certain exceptional circumstances, the I/O module queries the user for 
information needed for processing to continue or instructions on how to proceed. 

Querying is performed by the command_query_ subroutine. The user may intercept 
one or more types of query by establishing a handler for the command_question 
condition, which is signalled by the command_query_ subroutine. Alternately, the 
answer command can be used to intercept all queries. The use of a predetermined 
"yes" answer to any query causes those actions to be performed that attempt to 
complete an I/O operation without human intervention. 

In the following list of queries, status_code refers to command_question_info.status_code. 
See the Programmer's Reference Manual for information regarding the command_question 
condition and the command_question_info structure. 

status_code = error_table_$file_aborted 

This can occur only when the I/O switch is open for sequential_output The I/O 
module is unable to correctly write file header labels, trailer labels, or tapemarks. 
This type of error invalidates the structure of the entire file set. Valid file set 
structure can only be restored by deleting the defective file or file section from 
the file set 
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The user is queried for permission to delete the defective file or file section. If 
the response is "yes", the I/O module attempts deletion. The attempt may or may 
not succeed; the user is informed if the attempt fails. If the response is "no", no 
action is taken. The user is probably unable to subsequently process the file, or 
append files to the file set; however, this choice permits retrieval of the defective 
file with another I/O module. In either case, the I/O switch is closed. 

status_code = error_table_$unexpired_volume 

This can occur only when the I/O switch is open for sequential_output. A 
volume must be either reinitialized or overwritten; however, the first file or file 
section on the volume is unexpired. 

The user is queried for permission to initialize or overwrite the unexpired volume. 
If the response is "yes", the volume is initialized or overwritten and processing 
continues. If the response is "no", further processing cannot continue, and the 
I/O switch is closed. 

status_code = error_table_$uninitialized_volume 

A volume requires reinitialization or user verification before it can be used to 
perform any I/O. The I/O module distinguishes among four causes by setting 
command_question_info.query_code as follows: 

query_code = 1 

the first block of the tape is unreadable. The tape is either defective, or 

recorded at an invalid density. This query code can occur only if the I/O 
stream is opened for sequential_output. 

the first block of the tape is not a valid IBM VOL1 label. The tape is not 
formatted as an IBM SL volume. This query code can occur only if the I/O 
stream is opened for sequential_outpuL 

query_code = 3 

the volume identifier recorded in the VOL1 label is incorrect. The volume 
identifier does not match the volume name. 

query_code = 4 

the density at which the volume is recorded is incorrect The volume density 
does not match the specified density. This query code can occur only if the 
I/O stream is opened for sequential_output 

If the response is "yes", processing continues. If the response is "no", further 
processing cannot continue, and the I/O switch is closed. 

status_code = error_table_$unexpired_file 

This can occur only when the I/O switch is open for sequential_output A file 
that must be extended, modified, or replaced is unexpired. 
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The user is queried for permission to overwrite the unexpired file. If the 
response is "yes", processing continues. If the response is "no", further processing 
cannot continue, and the I/O switch is closed. 

status_code = error_table_$no_next_volume 

This can occur when reading a multivolume file, or when writing a file and 
reaching physical end of tape. The I/O module is unable to determine the name 
of the next volume, in the volume set 

The user is queried for permission to terminate processing. If the response is 
"yes", no further processing is possible. If the I/O switch is open for 
sequential_output, the I/O switch is closed. If the response is "no", the user is 
queried for the volume name of the next volume. (See status_code = 0 below.) 

status_code = 0 

This occurs only when the response to the above query is "no". The user is 
requested to supply the name of the next volume. The response must be a 
volume name 6 characters or less in length, optionally followed by a mount 
message. Even if the volume name begins with a hyphen, it must NOT be 
preceded by the -volume control argument If a mount message is to be 
specified, the response takes the following form: 

volume_name -comment STR 

where STR is the mount_message and need not be a contiguous string. See 

"Volume Specification" above. This is the only query that does not require a 

"yes" or "no" response. If a preset "yes" is supplied to all queries, this particular 
query never occurs. 



Structure Attribute Defaults 

When a file is created, the I/O module can supply a default value for any or all of 
the file structure attributes. The defaults used are as follows: 

1. record format - the default is F = vb 

2. block length - the default is B « 8192 

3. record length - 

F - u: undefined 

F = fb | f: R = block length 

F - vb | v: R - block length - 4 

F - vbs | vs: R « 1044480 
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An injudicious combination of explicit specifications and defaults can result in an 
invalid attribute set. For example, if -record 12000 is specified, applying the defaults 
produces the following: 

-format vb -block 8192 -record 12000 

This attribute set is invalid because, in vb format (see "Record Formats" below) the 
record length must be less than or equal to the block length minus 4. 

Overriding Structure Attributes 

Normally, the -format, -block, and -record control arguments are not included in the 
attach description of an I/O switch that is opened for sequentiaMnput; the structure 
attributes are extracted from the file labels. However, the I/O module permits the 
recorded structure attributes to be overridden by explicitly specified attach description 
control arguments. Because the apparent structure and characteristics of the file can be 
drastically altered, great care must be taken to ensure that attribute overrides do not 
produce unexpected and unwanted results. 

If a file has the following recorded attributes: 
-format fb -block 800 -record 80 

an explicit specification of the -format fb and -record 800 control arguments causes 
each block of ten 80-character records to be treated as a single 800-character record. 

If a file has the following recorded attributes: 

-format fb -block 800 -record 80 

an explicit specification of the -format fb, -block 80, and -record 80 control 
arguments causes the last 720 characters of every block to be discarded. No error is 
indicated, because every block of the file contains at least one 80-character record. 



Record Formats 

Files are structured in one of four record formats: F(B), V(B), V(B)S, or U. When a 
file is created, its record format should be chosen in accordance with the nature of 
the data to be recorded. For example, data consisting of 80-character card images is 
most economically recorded in FB format, blocked fixed-length records. Data 
consisting of variable length text lines, such as PL/ 1 source code produced by a text 
editor, is best recorded in VBS format, blocked spanned records, so that blanks are 
not inserted except after the last line. 
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With the exception of U format, files are either blocked or unblocked, blocked being 
the usual case. Each block of an unblocked file contains just one record, whereas 
each block of a blocked file can contain several records. Blocking can provide a 
significant savings of processing time, because several records are accessed with a single 
physical tape movement. Furthermore, as blocks are separated by distances of blank 
tape, blocking reduces the amount of tape needed to contain a file. 



F(B) Format 

In F format, records are of fixed (and equal) length, and files have an integral 
number (N) of records per block. If the file is unblocked, N equals 1 and the record 
length (R) equals the block length (B). If the file is blocked, N > 1 and B equals (R 
* N) where N is known as the blocking factor. 

For example, if R equals 800 and B equals 800, then the file is unblocked and each 
block contains just one record. 



data | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



block | 800 | | 800 | | 800 | | 800 | | 800 | | 800 | 



If R equals 800 and B equals 2400, then the file is blocked, the blocking factor is 3, 
and each block contains three records. 



data j 800 | j 800 j j 800 | | 800 | | 800 | j 800 | 



block | 800 | 800 | 800 | | 800 | 800 | 800 | 



The Standard for F format records permits recording short blocks. A short block is a 
block that contains fewer than N records, when N is greater than 1. Although the 
I/O module can read this variant of F format, it writes a short block in only one 
case. The last block of a blocked file can contain fewer than N records if there are 
no more records to be written when the file is closed. Therefore, blocked F format 
files written by the I/O module are always in FBS (fixed blocked standard) format 
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There are two special cases in which a datum is padded out to length R. The first 
case is that of iobl (the number of characters to be written) equals 0: a record of R 
blanks is written. When such a record is subsequently read, it is interpreted as a 
record of R blanks, and NOT as a zero-length record. The second case is that of 
0 < iobl > R: the record is padded on the right with blanks to length R, and the 
padded record written. When such a record is read, the original characters PLUS the 
padding are returned. The case of iobl greater than R is in error. 

V(B) Format 

In V format, records and therefore blocks may vary in length. Each record is 
preceded by a four-character record descriptor word (RDW) that contains the actual 
record length in binary, including the length of the RDW itself. Each block is 
preceded by a four-character block descriptor word (BDW) that contains the actual 
block length in binary, including the length of the BDW itself. 

V format files have an integral number of records per block, N. If the file is 
unblocked, B = R + 4; if blocked, B >= R + 4; For blocked records, the number of 
records per block varies indirectly with the size of the records. 



If R equals 804, B equals 808, and the file is unblocked, records of up to 800 
characters can be written, but each block can contain only one record. 



data 
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If R equals 804, B equals 808, and the file is blocked, records of up to 800 characters 
can be written. Each block can contain a maximum of 201 zero-length records (a 
record written as a 4-character RDW containing the binary value 4). 
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VfBJS Format 

In V(B)S format, a single record is formatted as one or more record segments. A 
record segment contains either a complete record, the initial portion of a record, a 
medial portion of a record, or the final portion of a record. No two segments of the 
same record can be contained in the same block, but a block may contain the 
segments of several different records. The maximum record length is limited only by 
the maximum size of a . storage system segment, currently 1,044,480 characters. 

V(B)S format files have an integral number of record segments per block. If the file 
is unblocked, each block contains only one record segment; if blocked, the number of 
record segments per block is variable. In either case, R and B are independent of one 
another. 

Each record segment begins with a four-character segment descriptor word (SDW). 
The SDW contains a four-character record segment length in binary, that includes the 
length of the SDW itself. (See "DOS Files" above.) The SDW also contains a 
one-character record segment code in binary, that indicates if the segment contains a 
complete record, or an initial, medial, or final portion. In the examples below, R 
equals 1000 and B equals 800. 
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U Format 

U format files contain records that do not conform to either F(B), V(B), or V(B)S 
format. A U format file is always unblocked. The record length is undefined, and 
the block length must equal or exceed the maximum record length. Blocks may vary 
in length. The special case of writing a record of less than 20 characters produces a 
block padded to length 20 with blanks. 



data 60 | | 127 I I 16 I I ^ 



block | 60 | | 128 | | 20 | | 156 



Volume Initialization 

The Standard requires that all volumes be initialized with VOL1 and dummy HDR1 
labels before they are used for output The I/O module provides a semiautomatic 
volume initialization mechanism that performs this operation as an integral part of the 
output function. It should be noted that, as stated above, a newly initialized volume 
contains a dummy HDR1 label, but not a dummy file. If a file is created on a newly 
initialized volume without an explicit specification of the -number control argument, 
the I/O module attempts to append it to the file set, resulting in an error. 



Conformance To Standard 

With one exception, the I/O module conforms to the Standard: the I/O module 
ignores the data set security field in the HDR1 label on input, and records it as 0 on 
output 



Label Processing 
VOL1 

The label is processed on input and output The owner-name and address-code-field, 
character positions (CP) 42 to 51, holds a three-character volume authentication 
code. 

UVL1 - UVL8 

These labels are not written on output and ignored on input 
HDR1/EOF1/EOV1 

The labels are processed on input and output The system-code-field, CP 61 to 
73, is recorded as "MULTICS IBM 
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HDR2/EOF2/EOV2 

The labels are processed on input and output. The 17-character 
job /job-step-identification-field, CP 18 to 34, is recorded as follows: 

"MULTICS /" || Julian creation date | | " 

HDR3/EOF3/EOV3 - HDR8/EOF8/EOV8 

These labels are not written on output and are ignored on input. 

UHL1/UTL1 - UHL8/UTL8 

These labels are not written on output and are ignored on input. 



Error Processing 

If an error occurs while reading, the I/O module makes 25 attempts to backspace and 
reread. If an error occurs while writing, the I/O module makes 10 attempts to 
backspace, erase, and rewrite. Should an error while reading or writing data prove to 
be unrecoverable, the I/O Module "locks" the file, and no further I/O is possible. 
I (See reset error^lock operation, below.) If an unrecoverable error occurs while writing 
file labels or tapemarks, the user is queried as to preserving the defective file versus 
file set consistency. (See "Queries" above.) If an unrecoverable error occurs during 
certain phases of volume switching or label reading, the I/O switch may be closed. 
The overriding concern of the error recovery strategy is: 



1. to maintain a consistent file set structure. 



2. to ensure the validity of data read or written. 



Close Operation 

The I/O switch must be open. 



List of Control Orders 

The I/O module supports eleven control operations. 



hardware_status 
status 

volume_status 

file_status 

feov 

close rewind 



retention 

retain_none 

retain_all 

reset_error_lock 

volume_density 



In the descriptions below, info_ptr is the information pointer specified in an 



iox_$control call. 
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hard ware jstatus Operation 

This operation returns the 72-bit IOM status string generated by the last tape I/O 
operation. The I/O switch must be open. The substr argument (IOM_bits, 3, 10) 
contains the major and minor status codes generated by the tape subsystem itself. (See 
MTS500 Magnetic Tape Subsystem, Order no. DB28 for an explanation of major and 
minor status.) The variable to which info_ptr points is declared as follows: 

declare IOM_bits bit (72) aligned; 



status Operation 

This operation returns a structure that contains an array of status codes, providing an 
interpretation of the IOM status string generated by the last tape I/O operation. 
These codes may be used in calls to the com_err_ subroutine, or may be converted to 
printable strings by calling the convert_status_code_ subroutine. (See the descriptions 
of the convert_status_code_ and the com_err_ subroutines.) The I/O switch must be 
open. The structure to which info^ptr points, device_status.incl.pll, is declared as 
follows: 
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del dstat_ptr pointer; 

del 1 devi ce_status based (dstat_ptr) , 

2 IOM_bits bit (72) aligned, /* I OM status */ 

2 n_m i nor fixed bin, /« number of minor codes*/ 

2 major fixed bin(35)» /* major status code */ 

2 minor (10) fixed bin (35); /* minor status codes */ 



volume_status Operation 

This operation returns a structure that contains the status of the current volume. If 
the I/O switch is open, the current volume is the volume on which the file section 
currently being processed resides. If the switch has never been opened, the current 
volume is the first (or only) volume in the volume set. If the switch was opened, but 
is now closed, the current volume is that on which the last file section processed 
resides. If the switch was closed by the I/O module as the result of an error while 
writing file header labels, trailer labels, or tapemarks, the current volume is the last 
(or only) volume in the volume set. The structure to which info_ptr points, 
tape_volume_status.incl.pll, is declared as follows: 

del tvstat_ptr pointer; 

del 1 tape_vol ume_status based (tvstat_ptr) , 

2 volume_name char (6) , /* volume name */ 

2 volume_id char (6) , /* from V0L1 label */ 

2 volume_seq fixed bin, /* order in volume set «/ 

2 tape_dr!ve char (8) , /* tape drive name */ 

/* "" if not mounted «/ 

2 read_errors fixed bin, /* read error count */ 

2 write_errors fixed bin; /* write error count */ 

In the current implementation of the I/O module, read_errors and write_errors are 
always zero. Eventually, the resource control package (RCP) supplies these values. 



file_status Operation 

This operation returns a structure that contains the current status of the file specified 
in the attach description. If the I/O switch has never been opened, no information 
can be returned; this situation is indicated by tape_file_status. state = 0. If the switch 
was opened, but is now closed, the current status of the file is its status just prior to 
closing. If the switch was closed by the I/O module as the result of an error while 
writing file header labels, trailer labels, or tapemarks, the entire file may have been 
deleted. In this case, the structure contains the current status of the previous file in 
the file set, if any. The structure to which info_ptr points, file_status.incl.pll, is 
declared as follows: 
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del tfstat_ptr pointer; 

del 1 tape_f i 1 e_status based (tf stat_ptr) , 



2 


state 


fixed bin, 


/* 


0 - no information */ 








/* 


1 - not open */ 








/* 


2 - open, no events */ 








/* 


3 - open, event lock */ 


2 


event code 


f i xed b i n (35) » 


/* 


error table code if 










state!=!3 */ 


2 


f i le_id 


char (17) , 


/* 


file i dent i f i er */ 








/* 


"" if -no labels */ 


2 


file seq 


f i xed bin, 


/* 


order in file set */ 


2 


cur sect i on 


f i xed bin, 


/* 


current or last 










section processed «/ 


2 


cur volume 


char (6) , 


/* 


volume name of volume 










on which cur section 










resides */ 


2 


pad 1 


f i xed bin, 


/* 


not used */ 


2 


pad2 


f i xed bin, 


/* 


not used */ 


2 


creat i on 


char (5) , 


/* 


Julian creation date */ 








/* 


"00000" if -no_ labels */ 


2 


expi rati on 


char (5) , 


/* 


Julian expiration date */ 








/* 


"00000" if -no_labels */ 


2 


f ormat_code 


fixed bin, 


/* 


1 - U format */ 








/* 


2 - F (B) format */ 








/* 


3 - V(B) format */ 








/* 


if - V(B)S format */ 


2 


blklen 


fixed bin, 


/* 


block length */ 


2 


reel en 


f i xed bi n (21) , 


/* 


record length */ 


2 


bl ocked 


bit(l) , 


/* 


"0"b - no | "l"b - yes */ 


2 


mode 


fixed bin, 


/* 


1 - ASCI 1 */ 








/* 


2 - EBCDIC */ 


2 


cur_bl kent 


f i xed bi n (35) ; 


/* 


current block count */ 



The "event" referenced in tape_file_status.state above is defined as an error or 
circumstance that prevents continued processing of a file. For example, parity alert 
while reading, reached end of information, no next volume available, etc. 



feov Operation 

This operation forces end of volume (feov) when writing a file. The switch must be 
open for sequential output. The operation is equivalent to detection of the end of 
tape reflective strip. The info_ptr should be a null pointer. 
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close_rewi nd Operation 

This operation specifies that the current volume is to be rewound when the I/O 
switch is next closed. info_ptr should be a null pointer. The switch need not be open 
when the operation is issued. The operation effects only one close; subsequent closings 
require additional control calls. 



retention, retainjione, retain_all Operations 

These operations cause the tape resources currently in use, i.e., tape drives(s) and tape 
volume(s), to be unassigned or retained at detach time according to the specified 
retention argument or operation. The info_ptr points to a fixed binary number with 
value as defined below: 

1 retention -none or retain_none 

causes none of the tape resources currently in use to remain assigned at detach 
time. 

2 retention -volume 

causes the tape volume(s) currently in use to remain assigned at detach time. 

3 retention -device 

causes the tape drives(s) currently in use to remain assigned at detach time. 

4 retention -all or retain_all 

causes all of the devices and volumes currently in use to remain assigned at 
detach time. 



reset _err or Jock Operation 

This operation unlocks the files so that further I/O is possible subsequent to a 
parity-type I/O error while reading. Such an error is indicated by a previous 
iox_$read_record or iox_$position call having returned the status code 
error_table_$tape_error. In this case, the value of tape_file_status.event_lock is 
error_table_$tape_error. (See file_status operation, above.) The I/O switch must be 
open for sequential_input. The info_ptr should be a null pointer. 

NOTE: IF RECORDS ARE BLOCKED AND/OR SPANNED, THE VALIDITY OF 
ANY RECORDS READ SUBSEQUENT TO A PARITY-TYPE I/O ERROR IS NOT 
GUARANTEED. (The parity error is reported for the first read of a logical record in 
the block. The actual location of the error in the block in unknown.) 



3-169 



AG93-05 



tape_ibm_ 



tape_ibm_ 



volume_density OPERATION 

This operation returns the encoded density of the volume set. The I/O switch need 
not be open. The variable to which info_ptr points is declared as follows: 

declare vol ume_dens i ty fixed bin; 

The values returned and their meanings are listed below: 
value meaning 

-1 none specified yet 



The I/O switch must be closed. If the I/O module determines that the membership 
of the volume set may have changed, the volume set members are listed before the 
set is demounted; volumes not listed are available for incorporation into other volume 
sets. If the volume set is unlabeled, only the name of the last volume processed is 
listed. 



Position Operation 

The I/O switch must be open for sequential_input. The I/O module does not support 
skipping backwards. In the course of a position operation, events or errors may occur 
that invoke the query mechanism. (See "Queries" above.) An unrecoverable error locks 
the file, and a severe error causes the I/O module to close the I/O switch. 



Read Length Operation 

The I/O switch must be open for sequential_input. In the course of a read_length 
operation, events or errors may occur that invoke the query mechanism. (See "Queries" 
above.) An unrecoverable error locks the file, and a severe error causes the I/O 
module to close the I/O switch. 



Read Record Operation 

The I/O switch must be open for sequential_input. 



2 

3 
h 



800 
1600 

6250 
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Write Record Operation 

The I/O switch must be open for sequential_outpuL 



Unlabeled Tapes 

The I/O module supports basic processing of unlabeled tapes that are structured 
according to the OS Tape Labels document mentioned at the beginning of this 
description. DOS leading tape mark (LTM) unlabeled format tapes cannot be 
processed. 

The -no_labels control argument specifies that unlabeled tapes are to be processed. 
The -no_labels control argument and any of the following control arguments are 
mutually exclusive: 

-name -extend 
-replace -modify 
-expires -dos 
-force 

Volume switching is handled somewhat differently for unlabeled tapes. When the I/O 
module detects a tape mark in the course of an input operation, it determines whether 
or not any volumes remain in the volume sequence list. If another volume appears in 
the list, volume switching occurs and processing continues on the next volume. If the 
list is exhausted, the I/O module assumes that end of information has been reached. 
Detection of end of tape during an output operation is handled in much the same 
way as it would be for a labeled tape. (See the OS Tape Labels document for a 
complete description of unlabeled volume switching strategy.) 
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Control Operations from Command Level 

All control operations supported by this I/O module can be executed from command 
level by using the io_call command. The general format is: 

io_call control switchname operation -control_arg 

where: 
switchname 

is the name of the I/O switch that is attached through the I/O mo.dule to an 
IBM tape file-set. 

operation 

is any of the control operations previously described and summarized below. 



operation abbreviation control_arg 



status st -all 

hardware_status hst 
reset_error_lock rel 
f i le_status f st 

vol ume_status vst 

retention ret -none, -volume, 

-devi ce, -al 1 

reta i n_a 1 1 reta 

retain_none retn 
close_rewind crw 

feov feov 



CONTROL ARGUMENTS 

are operation control arguments valid only for the retention and the status operations. 
A control argument is required for the retention operation. 

-none 

causes none of the tape resources currently in use to remain assigned at detach 
time. 

-volume 

causes the tape volume(s) currently in use to remain assigned at detach time, 
-device 
-all 

causes all of the devices and volumes currently in use to remain assigned at 
detach time. 
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The -all control argument is optional for the status operation. This control argument 
prints all available status information such as the device status, the volume status, the 
file status, and the hardware status. The -all control argument is only for use with 
the status operation through the io_call command. It is not defined for use in the 
status operation with iox_$control directly. 



Examples 

In the following examples, it must be emphasized that an attach description describes a 
potential operation, and in and of itself does nothing to the file. Depending upon the 
sequence of openings in various modes, one attach description can perform diverse 
functions. 

tape_ibm_ 0^+238 1 -nm ARD21 -cr -fmt vbs -ret all 

A file named ARD21 is to be appended to the file set whose first volume is 042381. 
If a file named ARD21 already exists in the file set, openings for sequential_input 
access that file, and openings for sequential_output replace the old file of that name. 
If no file named ARD21 already exists in the file set, openings for sequential_input 
prior to the first opening for sequential_output fail. The first opening for 
sequential_output creates the file by appending it to the end of the file set. 
Subsequent openings for sequential_input access the newly created file, and subsequent 
openings for sequential_output replace it. Spanned records are specified; the block 
length defaults to 8192, the record length to 1044480, and the encoding mode to 
EBCDIC. The density defaults to 1600 cpi, and the maximum number of devices 
defaults to 1. The volume set and devices are retained after detachment. 

tape_ibm_ 042381 -nm fargo.pl 1 -nb 2 -cr -force -fmt fb 
-bk 800 -rec 80 

A file named fargo.pll is created at position 2 in the file set. If a file named 
fargo.pll already exists at position 2, openings for sequential_input prior to the first 
opening for sequential_output access that file. The first opening for sequential_output 
creates a new file, and subsequent openings for sequential_input access the new file. 
If no file named fargo.pll exists at position 2, openings for sequential_input prior to 
the first opening for sequential_output fail. If a file exists at position 2, it is 
replaced irrespective of its expiration date. 

tape_ibm_ 042381 -nm zbx -rpl zbx -cr -md ascii -bk 6000 
-exp 2weeks 
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A file named zbx is created, replacing a file of the same name. Openings for 
sequential_input prior to the first opening for sequential_output access the old file. 
Each opening for sequential_output creates a new file, and each subsequent opening 
for sequential_input access the most recently created file. The specified encoding mode 
is ascii. The record format defaults to VB, and the record length defaults to 5996 
because the block length is specified as 6000. The file is protected from overwriting 
for a period of two weeks, so each opening for sequential_output subsequent to the 
initial opening for sequential_output causes the user to be queried for permission to 
overwrite. 

tape_ibm_ 04238 1 042382 -nb 14 -nib -cr -dv 3 

A file is to be created at position 14 on volume 042381. If a file already exists at 
position 14, an opening for sequential_input prior to the first opening for 
sequential_output accesses that file; otherwise, an error is indicated. Openings for 
sequential_output create new files, and openings for sequential_input subsequent to the 
first opening for sequential_output access the most recent creation. The default record 
format is VBS, the default block length 8192, and the default record length 1044480. 
The volume set is unlabeled. If the file exceeds the capacity of volume 042381, it is 
continued on volume 042382. If it then exceeds the capacity of volume 042382, the 
user is queried for instructions. A maximum of three devices can be used. 

tape_ibm_ 042381 042382 042383 -nm THESIS -ring 

A file named THESIS is to be read. The I/O switch can only be open for 
sequential_input. The volume set consists of at least three volumes, and they are 
mounted with write rings. Only one device can be used. 

tape_ibm_ 042381 -nm FF -nb 3 -ext -dv 4 -ret all 

A file named FF at position 3 in the file set is to be extended. Each opening for 
sequential_input accesses the current version. Each opening for sequential_output 
produces a new version. A maximum of four devices can be used. Resources are 
retained after detachment. 

tape_ibm_ 042381 -vol -COS -com i n_slot_000034 -nb 6 -mod -fc 

The file at position 6 in the file set is to be modified, irrespective of its expiration 
date. Each opening for sequential_input accesses the current version. Each opening for 
sequential_output produces a new version. The second volume of the volume set has 
volume identifier -COS, and can be found in slot 000034. 
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Attach Control Arguments 

The following is a complete list of all valid attach control arguments in both long and 
short forms: 

short 

control_arg form value of argument 



-block B 



•cl ear 
•create 
•density N 
■device N 
-dos 

•expires DATE 
•extend 
•force 
-format F 

•mode STR 
-mod i f y 
-name STR 

-no_l abel s 
-number N 
-record R 
-replace STR 
-retain STR 
-ring 



-bk B 



-cl 
■cr 

-den N 
-dv N 

-exp DATE 

•ext 

-fc 

-fmt F 

-md STR 
-mod 
-nm STR 

-nib 
-nb N 
-rec R 
-rpl STR 
-ret STR 
-rg 



20 <= B <= 32760 
mod (B,4) =0 if open for 
sequent i a l_output 



N = 800 I 1600 
1 <= N <= 63 

valid DATE 



6250 



F = fb I f I 
vbs I vs 
STR = ebcdic 



vb 



asc 1 i I b i nary 



STR <= 17 characters 

<* 8 characters (restricted subset) with -create 

1 <= N <= 9999 
1 <= R <= 1044480 
STR <= 17 characters 
STR = al 1 I none 



The following is a list of positional keywords: 



-comment STR 
-volume VNI 



-com STR STR <= 64 characters 

-vol VNI volume name <= 6 characters 



3-175 



AG93-05 



tape_mult_ 



tape_mult_ 



Name: tape mult 

The tape_mult_ I/O module supports I/O to and from Multics standard tapes. 
ATTACH DESCRIPTION 

tape_mult_ reel id {-control_args} 
ARGUMENTS 
reelid 

is the name of the tape reel to be mounted for this attachment. 

CONTROL ARGUMENTS 

-comment STR, -com STR 

specifies a comment string that is displayed to the operator. It can be used to 
give the operator any special instructions that are relevant to this attachment. The 
comment string must be enclosed within quotes if it contains blanks or other 
spacing characters. 

-density N, -den N 

specifies the density setting of the attached tape drive, where N can be 800, 1600, 
or 6250 bpi. The defaults are 800 for 7-track, and 1600 for 9-track. When 
opened for reading, the specified density is used only as a first guess. If the tape 
cannot be read at that density, tape_mult_ tries the other density. 

-error_tally, -et 

when opened for stream_input, displays an error summary on the user_output 
stream upon closing the tape I/O switch. This error summary includes: total 
number of read errors; number of errors that were successfully recovered for each 
of 1 to 7 backspace /re-read retries (each re-read using a different threshold 
and /or de-skew setting); number of errors that could not be recovered by 
backspace/ re-reading but were successfully recovered by reading forward and 
finding a good copy of the original record in error; and the number of times 
that both backspace /re-read and read forward recovery failed, but successful 
recovery was accomplished by backspacing two files, forward-spacing two files 
(thus positioning the tape at the beginning of the current file after tape motion 
past the tape cleaner and head in both directions dislodges any buildup of oxide 
particles on the tape or head surface) and then reading forward until original 
record in error was read successfully. This information is obtained from metering 
data kept in the tape_mult_ work segment, defined by tmdb.incl.pll. 

-speed S1{,S2,...,SN}, -ips SI {,S2, . . . ,SN} 

specifies desiTed tape drive speeds in inches per second, where Si can be 75, 125, 
or 200 inches per second. (See "Device Speed Specification" below.) 

-track N, -tk N 

specifies the track type of the tape drive that is to be attached, where N may be 
either 9 or 7. The default is 9. 
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-write, -wrt 

mounts the tape reel with a write ring. The default is to mount the tape reel 
without a write ring. 

-system, -sys 

increases tape performance by using more I/O buffers and other performance 
optimizations. Access to >system_control_l>rcp>workspace.acs or rcp_sys_ 
is required to use this control argument. 

-volume_set_name STR, -vsn STR 

specifies the contents of the volume set name field located in the tape label 
record (see the Programmer's Reference Manual for a description of the standard 
Multics tape label record). When opened for writing, STR is written into the 
volume_set_id field of the tape label record. If this control argument is not 
specified, the volume_set_id field will be set to blanks. When opened for reading, 
the volume_set_id field of the tape label is compared to STR. If they match or 
if the volume_set_id field is padded with .blanks, the open operation is allowed to 
be completed. If the volume_set_id field and STR do not match and the 
volume_set_id is not padded with blanks, error_table_$bad_label is returned. STR 
can be up to 32 characters in length. 

DEVICE SPEED SPECIFICATION 

The -speed control argument is used to specify acceptable tape device speeds in inches 
per second. The module only attaches a device that matches a speed specified by this 
control argument If more than one speed is specified, the module attaches a device 
that matches one of the speeds. 

OPENING 

The opening modes supported by tape_mult_ are stream_input and stream_output. If 
the opening mode is stream_output, the attach description must have specified the 
-write control argument. 

READ RECORD OPERATION 

The get_chars operation reads Multics standard records until either the caller's buffer 
is filled, or until the end of the tape volume is encountered. If not all the characters 
on a tape record fit into the caller's buffer, they are saved by the I/O module for 
the next get_chars call. 

WRITE RECORD OPERATION 

The put_chars operation formats the data into Multics standard records of 1024 data 
words each. Each record is written as it is filled. A partially filled record is not 
written onto the tape until it is filled with a subsequent put_chars operation, an 
error_count order is done, or the switch is closed. 
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LIST OF CONTROL ORDERS 

The tape_mult_ I/O module supports the control operation with three orders. 
error_count 

This order is supported only for the stream_output opening mode. It causes all 
output currently buffered to be written. An up-to-date error count is returned in 
the (fixed bin) variable referenced by the info_ptr argument. 

boot_program 

This order allows the specification of a boot program to be written into the tape 
label record (see the programmer's Reference Manual for a discussion of the 
bootable Multics tape label record format and function). The specified boot 
program must be coded in absolute self-relocating ALM assembly language and 
must be less than or equal to 832 (1500 octal) locations in length. The specified 
boot program is overlayed starting at absolute location 300 (octal) in the tape 
label record. When a Multics tape containing a bootable label record is 
bootloaded, control is transferred to location 300 via the tape label record transfer 
vector, the first 8 words of a bootable Multics tape label record. The I/O switch 
must be closed when this control order is executed. The specified boot program is 
written onto the tape label record when the tape is subsequently opened for 
output. The info_ptr must point to a structure of the following form: 

del 1 boot_program_i nf o based (info_ptr), 

2 version fixed bin, 

2 boot_program_ptr pointer, 
2 boot_program_text_l ength fixed bin (21), 
2 boot_program_name char (32) unaligned; 

where: 
version 

is the version number of this structure, currently 1. 
boot_program_ptr 

is a pointer to the beginning of the text section of the specified boot 
program. 

boot_program_text_length 

is the length in 36-bit words of the text section of the specified boot 
program. 

boot_program_name 

if nonblank, is the name of the boot program that the user wants recorded 
in the boot_pgm_path field of the label record. If boot_program_name is 
blank, then the absolute pathname of the boot program is written into the 
boot_pgm_path field of the label record. 
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get_boot_program 

This order allows a boot program to be extracted from the tape label when the 
tape is opened for input This control order must be issued immediately after the 
tape is opened for input and before the first read operation is begun. If it is 
executed later, then error_table_$no_operation is returned. The info_ptr must 
point to the boot_program_info struc s defined above for the boot_program 
control order. The user must set the version number. Then a pointer to a buffer, 
containing the extracted boot_program, its length, and the entryname portion of 
the boot_program_pathname, is returned to the user. If the get_boot_program 
control order is executed on a tape that has a standard tape label record, 
boot_program_ptr is set to null. 

CONTROL OPERATIONS FROM COMMAND LEVEL 

All control operations can be performed from the io_call command, as follows: 

io_call control switch order_arg 
ARGUMENTS 
switch 

is the name of the I/O switch. 

order_arg 

must be one of the following: 

error_count 
boot_program PATH 
get_boot_program 



Name: tape nstd 

The tape_nstd_ I/O module supports I/O to/from tapes in nonstandard or unknown 
formats. This module makes no assumptions about the format of the tape and returns 
one logical record for each physical record on the tape. Since the information upon 
the tape, including tape marks, is not interpreted by this I/O module, the user must 
detect the logical end of information on the reel. This I/O module functionally 
replaces ntape_. 

Entry points in the module are not called directly by users; rather, the module is 
accessed through the iox_ subroutine. See the Programmer's Reference Manual for a 
general description of the I/O system and for a discussion of files. 

ATTACH DESCRIPTION 

tape_nstd_ reel_num {-control_args} 
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ARGUMENTS 

reel_num 

is the tape reel number. 

CONTROL ARGUMENTS 

block N, -bk N 

specifies the maximum record length, in bytes, for this attachment. The default 
value for N is 11200. Values of N greater than 11888 require access to either the 
>system_l i brary_l>rcp_sys_ gate or >scl>rcp>workspace.acs (see "Buffer 
Size" below). 

-comment STR -com STR 

specifies a comment string that is displayed to the operator. It can be used to 
give the operator any special instructions that are relevant to this attachment. The 
comment string must be enclosed within quotes if it contains blanks or other 
spacing characters. 

-density N, -den N 

specifies the initial density to be used for this attachment. Acceptable values for 
N are 200, 556, 800, 1600 and 6250; the default is 800 bpi. 

-speed S1{,S2,...,SN}, -ips SI {,S2, . . . ,SN} 

specifies desired tape drive speeds in inches per second, where Si can be 75, 125, 
or 200 inches per second. (See "Device Speed Specification" below.) 

-track N, -tk N 

means that the tape is N track. Acceptable values for N are 7 and 9. If no 

track argument is supplied then 9 track is assumed. 

-write 

means that the tape is to be mounted with a write ring. This argument must 
occur if the I/O switch is to be opened for output or input/output. 

DEVICE SPEED SPECIFICATION 

The -speed control argument is used to specify acceptable tape device speeds in inches 
per second. The module only attaches a device that matches a speed specified by this 
control argument. If more than one speed is specified, the module attaches a device 
that matches one of the speeds. 

OPEN OPERATION 

The opening modes supported are sequential_input, sequential_output, and 

sequential_input_output. If an I/O switch attached via the tape_nstd_ I/O module is 

to be opened for output or input_output, the -write control argument must occur in 
the attach description. 
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LIST OF CONTROL ORDERS 

The following control operations are implemented by this I/O module: 
backspace_file 

positions the tape before the file mark next encountered while rewinding the tape 
(if no file mark is encountered then the tape is left at load point). 

backspace_record 

positions the tape before the previous record on the tape (or file mark if the 
current record is preceded by a file mark). 

bed 

sets hardware mode to binary coded decimal (BCD). See "Hardware Modes" 
below. 

binary 

sets hardware mode to binary (this is the default). See "Hardware Modes" below. 
data_security_erase 

erases the tape media from its current position to the end of tape (EOT) 
reflective marker. Additional "erase" control orders can be issued to erase any 
data written beyond the EOT reflective marker. No more than 40 additional erase 
control orders should be issued since the tape volume could run off the supply 
reel. 

d200 

sets density to 200 bpi. 

d556 

sets density to 556 bpi. 

d800 

sets density to 800 bpi. This is the default. 
dl600 

sets density to 1600 bpi. 
d6250 

sets density to 6250 bpi. 
erase 

erases tape for a distance of three inches from the current position, 
f ixed_record_length 

specifies that no record length information is expected by the caller since all data 
records are of a fixed length specified by a fixed bin(21) value. The record 
length is specified in bytes. 
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forward_file 

positions the tape past the next file mark encountered on the tape. 
forward_record 

positions the tape after the next record (or file mark if one follows the current 
record) encountered on the tape. 

io_call 

supports the io_call command protocol for orders that expect nonnull . info 
pointers. This order is prepared to interpret and print the status returned by the 
saved_status and request_status orders. 

nine 

sets hardware mode to eight/ nine bit conversion. See "Hardware Modes" below, 
protect 

sets write inhibit regardless of the presence of a write permit ring in the tape 
reel. The tape unit will remain write inhibited until the tape is detached. 

request_slaius 

interrogates the tape controller and returns its status as a bit(12) aligned quantity. 
reset_status 

causes all resettable statuses of the tape unit to be reset 
retry_count 

specifies a fixed bin(17) value which is the number of times an operation is to be 
retried before returning an error to the caller. The default value for the retry 
count is 10. 

rewind 

rewinds the tape to load point. 
saved_status 

returns the last status returned from the tape controller as a bit(12) aligned 
quantity. 

unload 

rewinds the tape and unloads it (done automatically when the tape is detached). 

write_eof 

writes an end of file mark (EOF). 

HARDWARE MODES 

In BCD mode, allowed only for 7-track drives, 6-bit characters are translated and 
then put on tape one character per frame. The translation is reversed on input. 
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tape_nstd. 



In nine mode, on output four 8-bit bytes are written from each word ignoring the 
high order bit of each 9— bit byte (by truncating it). On input, 8-bit characters are 
converted to 9-bit characters by forcing the high order bit to zero (by appending a 
zero-bit). This mode should be used to put ASCII or EBCDIC data on tape for 
transfer to other systems with 8-bit bytes. 

In binary mode, all 36 bits of each word are read or written. This mode should be 
used for native Multics applications where binary data is written to tape. 

9-track write 9 8-bit bytes (2 words) are written to 9 frames on tape. 

9-track read 9 frames are read into 9 8-bit bytes (2 words). 

7-track write 6 6-bit frames from each word. 

7-track read 6 frames on tape are read into 6 6-bit characters (1 word). 



7-track is 6 data + 1 parity track. 
9-track is 8 data + 1 parity track. 

CLOSE OPERATION 

The close operation rewinds the tape reel. The tape remains mounted, and positioned 
at the load point. No further I/O operations may be performed unless the I/O 
switch is opened again. 

DETACH OPERATION 

The detach operation unloads the tape. 

READ RECORD OPERATION 

The logical record returned by the read_record operation contains m=ceil(n/36) words, 
where n is the number of data bits in the physical record. The first n bits of the 
input record are the data bits, the last m-n bits are O's. The buffer supplied to the 
read_record operation must be word aligned. Read requests are retried 10 times before 
reporting an error unless a retry_count control order has been used to change the 
retry count. 

WRITE RECORD OPERATION 

The logical record supplied to the write_record operation must be word aligned, and 
must contain 0 mod 36 data bits. 

NOTES 

This I/O module violates those iox_ conventions that seem ill suited to processing raw 
tapes. In particular, read record and skip record operations may pass file marks. For 
example, if a tape contains two records, A and B, separated by a file mark, then the 
first read request would read record A, a second read request would return 
error_table_$end_of_info, and a third read request would return record B. 
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BUFFER SIZE 

The maximum number of bytes that may be transmitted on a read_record or 
write_record operation is 180224, less overhead. This limit may be administratively 
restricted to a lower value. To use the full capability, the caller may need access to 
>system_l i brary_l>rcp_sys_ or >sc l>rcp>workspace.acs . 



Name: tc io 

The tc_io_ I/O module supports terminal independent I/O to the screen of a video 
terminal. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system interfaces iox_. 

ATTACH DESCRIPTION 



tc_io_ {device} {-control_args} 



ARGUMENTS 
device 

is the channel name of the device to be attached If a device is not given, the 
-login_channel control argument must be given. 

CONTROL ARGUMENTS 

-login_channel 

specifies attachment to the user's primary login channel. If a device is not 
specified, then the user's login channel is used. This control argument flags this 
switch for reconnection by the process disconnection facility. If the user's login 
device should hang up, this switch will be automatically closed, detached, attached, 
and opened on the user's new login channel when the user reconnects, if 
permission to use this facility is specified in the SAT and PDT for the user. 

-destination DESTINATION 

specifies that the attached device is to be called using the address DESTINATION. 
In the case of telephone auto_call lines, DESTINATION is the telephone number 
to be dialed. See the dial_manager_ subroutine in the Muliics Subroutines and 
1 10 Modules manual, Order No. AG93, for more details. 
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-no_block 

specifies that the device is to be managed asynchronously. The tty_ subroutine 
will not block to wait for input to be available or output space to be available. * 
This control argument should not be used on the login channel, because it will 
cause the command listener to loop calling get_chars. 

-no_hangup_on_detach 

prevents the detach entry point from hanging up the device. This is not 
meaningful for the login channel. 

-hangup_on_detach 

causes the detach entry point to hang up the device automatically. This is not 
meaningful for the login channel. 

OPEN OPERATION 

Opens the module for stream_input_outpuL 

GET LINE OPERATION 

The get_line operation is not supported. 

CONTROL OPERATION 

The following control orders are supported: 

clear_screen 

clears the entire terminal screen. The info_ptr is null. It is intended for use 
when the screen image may have been damaged due to communications problems, 
for example. 

get_capabilities 

returns information about the capabilities of the terminal. The info structure is 

described in the description of the "get_capabilities" control order in the 
window_io_ module. 

get_break_table 

returns the current break table. The info pointer should point to a break table, 
declared as follows (window_control_info.incl.pll): 

del 1 break_tabl e_i nf o aligned based (break_tab 1 e_ptr) , 
2 version fixed bin, 

2 breaks (0:127) bit (1) unaligned; 
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STRUCTURE ELEMENTS 



version 

must be set by the caller to break_table_infc_version_l. (Input) 
breaks 

has a "l"b for each character that is a break character. (Output) 
set_break_table 

sets the break table. The info pointer should point to a break table as defined 
by the get_break_table order, above. By default, the break table has "l"b for all 
nonprintable characters, and "0"b elsewhere. Applications that set the break table 
must be careful to reset it afterwards, and establish an appropriate cleanup 
handler. 

set_line_speed 

sets the speed of the terminal's connection to Multics. The info_ptr should point 
to a fixed binary number representing the line speed in characters per second. 
Negative line speeds are not allowed. 

set_term_type 

changes the terminal type. The info pointer should point to a set_term_type_info 
structure, described below. This sets window_status_pending for all windows and 
sets the ttp_change field in the window_status structure along with the screen_in valid. 
This operation re-initializes all the terminal specific video system information such 
as the video sequences, length and width of the screen, and capabilities. It is 
equivalent to doing "window_call revoke; stty -ttp new_terminal_type; window_call 
invoke", except no windows are destroyed. The set_term_type_info structure is 
declared m set term type mfo.mcl.pll! 

del 1 set_term_type_i nf o aligned based (sttip) 

2 version fixed bin 

2 name char (32) unaligned 

2 f 1 ags unal i gned 

3 send_i ni t i al_str i ng bit (1) 

3 set_modes bit (1) 

3 i gnore_l i ne_type bit (1) 

3 mbz ~ bit (33) ; 



STRUCTURE ELEMENTS 



version 

is the version of this structure. (Input) It must be stti_version_l. 
name 

is the name of the new terminal type. (Input) 
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NOTES 



The send_initial_string, set_modes and ignore_line_type flags are all ignored by the 
video system. The initial string will always be sent. 

reconnection 

determines the new terminal type (which may or may not be the same as before 
the disconnection). Performs a set_term_type control order to inform the rest of 
the system of the change in terminal type. If the set_term_type fails then the 
video_utils_$turn_off_login_channel is invoked in an attempt to re-attach tty_. 
Reconnection (a field in window_status) is set to indicate to an application doing 
get_window_status that a reconnection has occurred. 

The window_status_info structure is declared in window_status.incl.pll. 



Name: tty 

The tty_ I/O module supports I/O from/to devices that can be operated in a 
typewriter-like manner, e.g., the user's terminal. 

Entry points in the module are not called directly by users, rather, the module is 
accessed through the I/O system. See the Programmer's Reference Manual for a 
general description of the I/O system. 

ATTACH DESCRIPTION 

tty_ {device} {-control_args} 

ARGUMENTS 

device 

is the channel name of the device to be attached (channel names are described in 
Appendix B of the Programmer's Reference manual). If a device is not given, one 
of the -login_channel or -dial_id control arguments must be given. The star 
convention is allowed. 

CONTROL ARGUMENTS 

-destination DESTINATION 

this control argument specifies that the attached device is to be called using the 
address DESTINATION. In the case of telephone auto_call lines, DESTINATION 
is the telephone number to be dialed. Use of this control argument requires the 
dialok attribute. 
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When the destination specifies an X.25 address it may optionally be preceded by 
"*" or "x29," to indicate that an X.29 (PAD) call should be made. For example, 
a destination of 

x.29,3106:mitmul or 
*3106:mitmul 

specifies an X.29-type call on TYMNET. 

-dial.id STR 

specifies that dial connections are to be accepted on the dial_id STR. Use of this 

control argument requires the dialok attribute. The dial command is then used to 

connect a terminal on the dial_id STR. If STR is not a registered dial_id, then 
the Person_id. Projected of the process being connected to must be supplied to 
the dial command. For example: 

! dial STR Person. Project 

To become a registered server, the process must have rw access to 
>scl>rcp>di al .STR.acs. 

-hangup_on_detach 

causes the detach entrypoint to hang up the device automatically. This is not 
meaningful for the login channel. 

-login_channel 

specifies attachment to the user's primary login channel. This control argument 
flags this switch for reconnection by the process disconnection facility. If the 
user's login device should hang up, this switch is automatically closed, detached, 
attached, and opened on the user's new login channel when the user reconnects, if 
permission to use this facility is specified in the SAT and PDT for the user. 

-no_block 

specifies that the device is to be managed asynchronously. The tty_ module does 
not block to wait for input to be available or output space to be available (see 
"Buffering" below). This control argument should not be used on the login 
channel, because it causes the command listener to loop calling getjine. 

-no_hangup_on_detach 

prevents the detach entrypoint from hanging up the device. This is not 
meaningful for the login channel. 

-no_suppress_dial_manager 

enables dial_manager_, and is the default 
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-resource STR 

specifies the desired characteristics of a channel. STR (which can be null) consists 
of reservation attributes separated by commas. The channel used by a dial-out 
operation must have the characteristics specified in the reservation string. 
Reservation attributes consist of a keyword and optional argument Attributes 
allowed are: 

baud_rate=BAUD_RATE 
line_type=LINE_TYPE 

where BAUD_RATE is a decimal representation of the desired channel line speed 
and LINE_TYPE is a valid line type, chosen from line_types.incl.pll (see 
"set_line_type", below). 

-required_access_class STR 

specifies the access class that must be associated with the channel. STR is an 
access class string. The access class specified must be the same as the process's 
authorization unless the process has the "comm" privilege turned on, in which case 
the access class specified must be less than or equal to the process's authorization. 

-suppress_dial_manager 

prevents tty_ from using dial_manager_ to attach the specified channel. If the 
channel cannot be attach via a call to hcs_, the attach operation fails. 

NOTES 

The device specified must be available to the attaching process. The user's login device 
is always available. Any devices acquired with the dial_manager„ subroutine are also 
available. If the device is in slave service, and the user has appropriate access to its 
access control segment (rw to >scl>rcp>NAME .acs) , tty_ attempts to make it 
available using the privileged_attach mechanism of dial_manager_. If the -destination 
control argument is specified, the dial_out mechanism is used (the user must have rw 
access to >scl>rcp>NAME .acs) . If the -dial_id control argument is specified, the 
allow_dials or registered_server mechanism is used. 

OPENING 

The opening modes supported are stream_input, stream_output, and stream_input_output 
EDITING 

To control editing, use the modes operation. Details on the various modes are given 
below. 
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BUFFERING 

This I/O module blocks to await either the availability of input characters or the 
availability of output buffer space, unless the -no_block control argument is specified 
in the attach description. If the -no_block attach description control argument is 
specified, the behavior of the iox_$put_chars, iox_$get_chars, and iox_$get_line calls 
changes. If the put_chars entrypoint cannot write all the characters supplied, it returns 
a nonstandard status code consisting of the negative of the number of characters 
actually not written (returns -(number not written)). Any positive status code should 
be interpreted as a standard system status code. The get_chars and get_line entrypoints 
will return zero status codes and zero characters read if there is no input available. 

INTERRUPTED OPERATIONS 

When an I/O operation (except detach) being performed on a switch attached by this 
I/O module is interrupted by a signal, other operations can be performed on the 
switch during the interruption. If the interrupted operation is get_line, get_chars, or 
put_chars and another get_line, get_chars, or put_chars operation is performed during 
the interruption, the "start" control operation should be issued before the interrupted 
operation is resumed. 

GET CHARS OPERATION 

The get_chars operation reads as many characters as are available, up to, but not 
exceeding, the number requested by the caller. No error code is returned if the 
number of characters read is less than the number requested. At least one character is 
always returned (unless the number requested is zero). The characters read may 
comprise only a partial input line, or several input lines; no assumptions can be made 
in this regard. 

GET LINE OPERATION 

The get_line operation is supported. No error code is returned if the read operation 
occurs with the input buffer length at zero. For further explanation, see the 
iox_$get_line entry. 

PUT CHARS OPERATION 

The put_chars operation is supported (see the iox_$put_chars entry). 
CONTROL OPERATION 

The following orders are supported when the I/O switch is open. Except as noted, 
the info_ptr should be null. The orders are divided into categories. Local orders 
perform a specific function one time only, global orders change the way the system 
interfaces with the terminal, and other orders fit in neither category. Control orders 
are performed through the iox_$control entry. 
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LIST OF LOCAL ORDERS 



abort 

flushes the input and output buffers. 



get_chars_timeout 

performs a get_chars operation, with a timeout specified. The preferred method 

to using this control order is to use the timed_io_$get_chars subroutine. The 

info_ptr points to the following structure (declared in io_timeout_info.incl.pll): 

del 1 i nput__t imeout_i nfo, 

2 timeout fixed bin (71) » 

2 buf f er_poi nter ptr, 

2 buf fer_length fixed bin (21), 

2 characters read fixed bin (21); 



where the buffer_pointer, bufferjength. and characters_read elements are the 
same as the corresponding arguments to iox_$get_chars (Input). The timeout 
element is the number of microseconds tty_ will wait before returning 
error_table_$timeout (Input). 

get_line_timeout 

performs a get_line operation, with a timeout specified. The preferred method to 
using this control order is to use the timed_io_$get_line subroutine. The 
info_pointer points to the same structure as that specified for get_chars_timeout. 

hangup 

disconnects the telephone line connection of the terminal, if possible. This makes 
the terminal unavailable for further use. 



interrupt 

sends an out-of-band interrupt signal (quit signal) to the terminal, 
listen 

sends a wakeup to the process once the line associated with this device identifier 
is dialed up. 

printer_off 

causes the printer mechanism of the terminal to be temporarily disabled if it is 

physically possible for the terminal to do so; if it is not, the status code 

error_table_$action_not_performed is returned (see "Notes" below). 

position 

the I/O switch must be open for stream input The I/O module reads and 
discards the number of lines specified by the call. 

printer_on 

causes the printer mechanism of the terminal to be re-enabled (see "Notes" 
below). 
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put_chars_timeout 

performs a put_chars operation, with a timeout specified. The preferred method 
to using this control order is to use the timed_io_$put_chars subroutine. The 
info_ptr points to the following structure (declared in io_timeout_info.incl.pll): 

del 1 output_t imeout_i nf o, 

2 timeout fixed bin (71) , . 

2 buf f er_poi nter ptr, 

2 buf fer_length fixed bin (21), 

2 characters_wr i tten fixed bin (21); 

resetread 

flushes the input buffer. 

resetwrite 

flushes the output buffer. 

wru 

initiates the transmission of the answerback of the device, if it is so equipped. 
This operation is allowed only for the process that originally attached the device 
(generally the initializer process). The answerback can subsequently be read by 
means of the get_chars input/ output operation. 

LIST OF GLOBAL CONTROL ORDERS 

accept_printer_of f 

causes subsequent printer_off and printer_on orders to be accepted if possible. 
get_channel_info 

returns the name of the attached channel and its hardcore device index. The 
info_ptr must point to the following structure (defined in 
tty_get_channel_inf o.incl.pll): 

del 1 tty_get_channel_i nf o aligned based, 

2 version fixed bin, 

2 devx fixed bin, 

2 channel _name char (32) ; 

where: 
version 

is the version of this structure. (Input). It must be set to 
tty_get_channel_inf o_version. 

devx 

is the hardcore device index for the channel. (Output) 

channel_name 

is the name of the channel. (Output) 
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get_delay 

is used to find out what delay values are currently in effect The info_ptr points 
to the structure described for set_delay (below), which is filled in as a result of 
the call (except for the version number, which must be supplied by the caller). 

get_editing_chars 

is used to find out what input editing characters are in effect. The info_ptr 
points to the structure described below for set_editing_chars, which is filled in as 
a result of the call (except for the version number, which must be supplied by 
the caller). 

get_f raming^chars 

causes the framing characters currently in use to be returned (see the 
set_framing_chars order below). If no framing characters have been supplied, 
NUL characters are returned. The info_ptr must point to a structure like the one 
described for the set_framing_chars order; this struc 
the call. 

get_ifc_info 

causes the characters currently in use for input flow control to be returned (see 
the input_flow_control_chars order below). The info_ptr must point to a structure 
like the one described for the input_flow_control_chars order, which is filled in 
as a result of the call. If no characters are currently set, the count fields are set 
to 0. 

get_input_translation 

get_output_translation 

get_input_conversion 

get_output_con version 

these orders are used to obtain the current contents of the specified table. The 
info_ptr points to a structure like the one described for the corresponding "set" 
order below, which is filled in as a result of the call (except for the version 
number, which must be supplied by the caller). If the specified table does not 
exist (no translation or conversion is required), the status code error_table_$no_table 
is returned. 

get_ofc_info 

causes the characters and protocol currently in use for output flow control to be 
returned (see the output_flow_control_chars order below). The info_ptr must point 
to a structure like the one described for the output_flow_control_chars order, 
which is filled in as a result of the call. If no output flow control protocol is 
currently in use, the count fields are set to 0, and both suspend_resume and 
block_acknowledge are set to "0"b. 
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get_special 

is used to obtain the contents of the special_chars table currently in use. The 
info_ptr points to the following structure (defined in tty_convert.incl.pll): 

del 1 get_speci a 1 _ i nfo_struc aligned, 
2 area__ptr ptr, 
2 tab1e_ptr ptr; 

where: 
area_ptr 

points to an area in which a copy of the current special_chars table is 
returned. (Input) 

table_ptr 

is set to the address of the returned copy of the table. (Output) 
hangup_proc 

allows you to establish a procedure that is called when the communications line to 
the device hangs up. 

input_flow_control_chars 

specifies the character(s) to be used for input flow control for terminals with line 
speed input capability. The terminal must be in if low mode for the feature to 

take effect. The info_ptr must point to the following structure (declared in 
f low_control_inf o.incl.pll): 

del 1 i nput_f 1 ow_cont.ro l__i nfo aligned, 

2 suspend__seq unaligned, 

3 count fixed bin (9) unsigned, 

3 chars char (3) , 

2 resume_seq unaligned, 

3 count fixed bin (9) unsigned, 

3 chars char (3) , 

2 t imeout bi t (1) ; 
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wnere: 
suspend_seq 

is the character sequence that the system sends to tell the terminal to stop 
sending input, or that the terminal sends to inform the host that it is 
suspending input count is an integer from 0 to 3 that specifies the number 
of characters in the sequence, chars are the characters themselves. At present, 
only sequences of length 0 or 1 are supported. 

resume_seq 

is the character sequence to be sent by the system to the terminal to tell it 
to resume transmission of input count is an integer from 0 to 3 that 
specifies the number of characters in the sequence, chars are the characters 
themselves. 

timeout 

is "l"b if the resume character is to be sent to the terminal after input has 
ceased for one second, whether or not a suspend character has been received. 

output_flow_control_chars 

enables either of two output flow control protocols and specifies the characters to 
be used for output flow control. The terminal must be in of low mode for the 
feature to take effect. The info_ptr must point to the following structure 
(declared in flow_control_info.incl.pll): 

del 1 output_f 1 ow_control_i nf o aligned, 

2 f 1 ags una 1 i gned, 

3 suspend_resume bit(l), 

3 block_acknowledge bit(l), 

3 mbz bit (16) , 

2 buffer_size fixed bin(l8) unsigned unaligned, 

2 suspend_or_etb_seq unaligned, 

3 count fixed bin(9) unsigned, 

3 chars char (3) , 

2 resume_or_ack_seq unaligned, 

3 count fixed bin (9) unsigned, 

3 chars char (3) ; 

where: 

suspend_resume 

is "l"b to specify a suspend /resume protocol. 

block_acknowledge 

is "l"b to specify a block acknowledgement protocol. 

buffer_size 

is the number of characters in the terminal's buffer if block_acknowledge is 
"l"b; otherwise, it is ignored. 
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suspend_or_etb_seq 

is the character sequence sent by the terminal to tell the system to suspend 
output if suspend_resume is "l"b, or the end_of_block character sequence if 
block_acknowledge is "l"b. count is an integer from 0 to 3 that specifies the 
number of characters in the sequence, chars are the characters themselves. 

resume_or_ack_seq 

is the character sequence sent by the terminal to indicate that output can be 
resumed if suspend_resume is "l"b, or the character sequence sent by the 
terminal to acknowledge completion of a block if block_acknowledge is "l"b. 
count is an integer from 0 to 3 that specifies the number of characters in 
the sequence, chars are the characters themselves. 

ref use_printer_of f 

causes subsequent printer_off and printer_on orders to be rejected, except when in 
echoplex mode. 

set_delay 

sets the number of delay characters associated with the output of carriage-motion 

characters. The info_ptr points to the following structure (defined in 
tty_convert.incl.pll): 



delay_struc 


based 


al igned, 


2 version 


f i xed 


bin, 


2 default 


f i xed 


bin, 


2 delay, 






3 vert_nl 


f i xed 


bin, 


3 horz_nl 


float 


bin, 


3 const_tab 


f i xed 


bin, 


3 var_tab 


float 


bin, 


3 backspace 


f i xed 


bin, 


3 vt_ff 


f i xed 


bin; 



where: 
version 

is the version number of the structure. It must be 1. 
default 

indicates, if nonzero, that the default values for the current terminal type 
and baud rate are to be used and that the remainder of the structure is to 
be ignored. 

vert_nl 

is the number of delay characters to be output for all newlines to allow for 
the linefeed (-127 <= vert_nl <= 127). If it is negative, its absolute value is 
the minimum number of characters that must be transmitted between two 
linefeeds (for a device such as a TermiNei 1200). 
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horz_nl 

is a number to be multiplied by the column position to obtain the number 
of delays to be added for the carriage return portion of a newline 
(0 <= horz_nl <= 1). The formula for calculating the number of delay 
characters to be output following a newline is: 

ndelays = vert_n1 + fixed (horz_nl *col umn) 
const_tab 

is the constant portion of the number of delays associated with any 
horizontal tab character (0 <~ const_tab <= 127). 

var_tab 

is the number of additional delays associated with a horizontal tab for each 
column traversed (0 <= var_tab <= 1). The formula for calculating the 
number of delays to be output following a horizontal tab is: 

ndelays = const_tab + fixed (var_tab*n_col umns) 
backspace 

is the number of delays to be output following a backspace character 
(-127 <= backspace <= 127). If it is negative, its absolute value is the 
number of delays to be output with the first backspace of a series only (or a 
single backspace). This is for terminals such as the TermiNet 300 that need 
delays to allow for hammer recovery in case of overstrikes, but do not 
require delays for the carriage motion associated with the backspace itself. 

vt_ff 

is the number of delays to be output following a vertical tab or formfeed 
(0 <=vt_ff <= 511). 

set_editing_chars 

changes the characters used for editing input The info_ptr points to the 
following structure (declared in tty_editing^chars.incl.pll): 

del 1 ed i t i ng_chars aligned, 

2 version fixed bin, 

2 erase char(l) unaligned, 

2 kill char(l) unaligned; 
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where: 



version 

is the version number of this structure. It must be 2. 



erase 

is the erase character. 

kill 

is the kill character. 
The following rules apply to editing characters: 

1. The two editing characters cannot be the same. 

2. No carriage-movement character (carriage return, newline, horizontal tab, 

backspace, vertical tab, or formfeed) can be used for either of the editing 
functions. 

3. NUL and space cannot be used for either editing function. 

4. If the editing character is an ASCII control character, it will not have the 

desired effect unless ctl_char mode is on (see "Modes Operation" below). 

set_f raming_chars 

specifies the pair of characters that the terminal generates surrounding input 
transmitted as a block or "frame." These characters must be specified in the 
character code used by the terminal. This order must be used for blk_xfer mode 
(see below) to be effective. The info_ptr must point to a structure with the 
following format: 

del 1 f rami ng_chars aligned, 

2 frame_begin char(l) unaligned, 
2 frame_end char (1) unaligned; 



set_input_conversion 

provides a table to be used in converting input to identify escape sequences and 
certain special characters. The info_ptr points to a structure of the following 
form (defined in tty_convert.incl.pll): 

del 1 cv_trans_struc aligned, 

2 version fixed bin, 

2 default fixed bin, 

2 cv_trans al i gned, 

3 value (0 : 255) fixed bin (8) unaligned; 
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where: 
version 

is the version number of the structure. It must be 1. 
default 

indicates, if nonzero, that the default table for the current terminal type is 
to be used, and the remainder of the structure is ignored. 

values 

are the elements of the table. This table is indexed by the value of a typed 
input character, and the corresponding entry contains the ASCII character 
resulting from the translation. If the info_ptr is null, no translation is to be 
done. 

NOTE: In the case of a terminal that inputs 6-bit characters and case-shift 
characters, the first 64 characters of the table correspond to characters in 
lower shift, and the next 64 correspond to characters in upper shift. 

The table is indexed by the ASCII value of each input character (after translation, 
if any), and the corresponding entry contains one of the following values 
(mnemonic names for these values are defined in tty_convert.incl.pll): 

0 ordinary character 

1 break character 

2 escape character 

3 character to be thrown away 

4 formfeed character (to be thrown away if page length is nonzero) 

5 this character and immediately following character to be thrown 
away 

set_input_translation 

provides a table to be used for translation of terminal input to ASCII. The 
info_ptr points to a structure of the following form (declared in tty_convert.incl.pll): 

del 1 cv_trans_struc aligned, 

2 version fixed bin, 

2 default fixed bin, 

2 cv_trans al igned, 

3 value (0 : 255) char(l) unaligned; 

where version, default, and value are as described in the cv_trans_struc structure 
used with the set_input_conversion order above. 
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set_line_type 

sets the line type associated with the terminal to the value supplied. The info_ptr 
should point to a fixed binary variable containing the new line type. Line types 
can be any of the following named constants defined in the include file 
line_types.incl.pll: 

LINE.ASCII 

device similar to 7-bit ASCII using Bell 103-type modem protocol. 

LINE.SYNC 

synchronous connections, no protocol. 

LINE_G115 

ASCII synchronous connection, Model G-115 remote computer protocol. 

LINE.BSC 

binary synchronous protocol. 

LINE_VIP 

device similar to Honeywell Model 7700 Visual Information Projection (VIP) 
stand— alone terminal. 

LINE_ASYNC1 
LINE_ASYNC2 
LINE_ASYNC3 

site-supplied asynchronous protocols. 

LINE.SYNC1 
LINE.SYNC2 
LINE_SYNC3 

site-supplied synchronous protocols. 
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LINE_POLLED_VIP 

device similar to Honeywell Model 7700 Visual Projection System (VIP) polled 
terminal concentrator subsystem. 

LINE_X25LAP 

X.25 network connection using the link access protocol (LAP). 
LINE.COLTS 

special software channel used for Communications Online Test and Diagnostics 
System. 

This operation is not permitted while the terminal is in use. 
set_output_conversion 

provides a table to be used in formatting output to identify certain kinds of 
special characters. The info_ptr points to a structure like that described for 
set_input_conversion (above). The table is indexed by each ASCII output character 
(before translation, if any), and the corresponding entry contains one of the 
following values (mnemonic names for these values are defined in tty_convert.incl.pll): 

0 ordinary character. 

1 newline. 

2 carriage return. 

3 horizontal tab. 

4 backspace. 

5 vertical tab. 

6 formfeed. 

7 character requiring octal escape. 

8 red ribbon shift. 

9 black ribbon shift 

10 character does not change the column position. 

11 this character together with the following one do not change 
the column position (used for hardware escape sequences). 

12 character is not to be sent to the terminal. 

17 or greater a character requiring a special escape sequence. The indicator value 
is the index into the escape table of the sequence to be used, plus 16. The 
escape table is part of the special characters table; see the set_special order 
below. 
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set_output_translation 

provides a table to be used for translating ASCII characters to the code to be 
sent to the terminal. The info_ptr points to a structure like that described for 
set_input_translation. The table is indexed by the value of each ASCII character, 
and the corresponding entry contains the character to be output If the info_ptr 
is null, no translation is to be done. 

NOTE: For a terminal that expects 6-bit characters and case-shift characters, the 
400(8) bit must be turned on in each entry in the table for a character 
that requires upper shift, and the 200(8) bit must be on in each entry 
for a character that requires lower shift. 

set_special 

provides a table that specifies sequences to be substituted for certain output 
characters, and characters that are to be interpreted as parts of escape sequences 
on input Output sequences are of the following form (defined in tty_convertincl.pll): 

del 1 c_chars based aligned, 

2 count fixed bin (8) unaligned, 

9 chare ( char ( "\\ unal InnoH' 

— — • — ■ — v.// »»..«.. \ ■ / 

where: 
count 

is the actual length of the sequence in characters (0 <- count <= 3). If 
count is zero, there is no sequence. 

chars 

are the characters that make up the sequence. 
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The info_ptr points to a structure of the following form {defined in 
tty_convert_incl.pll): 



del 1 



spec ial_chars_struc 


a 


igned basec 








vers i on 


f 


xed bin, 






z 


41 1 1 4* 

det au i t 


f 


xed bin, 






2 


speci al_chars 












3 n1_seq 


a 


1 i gned 1 i ke 


c_ 


chars, 




3 cr_seq 


a 


1 i gned 1 i ke 


c_ 


chars , 




3 bs_seq 


a 


i gned 1 i ke 


c_ 


chars, 




3 tab_seq 


a 


1 i gned 1 i ke 


c_ 


chars, 




3 vt seq 


a 


1 i gned 1 i ke 


c_ 


chars, 




3 ff_seq 


a 


1 i gned 1 i ke 


c_ 


chars , 




3 printer_on 


a 


1 i gned 1 i ke 


c_ 


chars , 




3 printer_off 


a 


1 i gned 1 i ke 


c_ 


chars , 




3 red_r i bbon_sh i f t 


a 


1 i gned 1 i ke 


c_ 


chars , 




3 bl ack_r i bbon_sh i f t 


a 


1 i gned 1 i ke 


c_ 


chars, 




3 end_of_page 


a 


1 i gned 1 i ke 


c_ 


chars, 




3 escape_l ength 


f 


ixed bin, 








3 not_ed i ted_escapes 


( 


sc_escape_l en 


refer 



3 ed i ted_es capes 



3 i nput_escapes 
h 1 en 

k sir 



3 i nput_resul ts 
h pad 
h str 



(special_chars.escape_length) ) 
1 i ke c_chars , 
(sc_escape_l en refer 

(s pec i a l_chars.escape_ length) ) 
1 i ke c_chars , 
al i gned, 

fixed bin (8) unaligned, 

char (sc_i nput_escape_i en refer 

(special_chars. i nput_escapes . len)) 

unal i gned , 
al i gned, 

bi t (9) unal i gned, 

char (sc_i nput_escape_l en refer 

(special_chars. i nput_escapes . len)) 

unal i gned; 



where: 
version 

is the version number of this structure. It must be 1. 



default 

indicates, if nonzero, that the default values for the current terminal type 
and baud rate are to be used and that the remainder of the structure is to 
be ignored. 

nl_seq 

is the output character sequence to be substituted for a newline character. 
The nl_seq. count generally should be nonzero. 
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cr_seq 

is the output character sequence to be substituted for a carriage-return 
character. If count is zero, the appropriate number of backspaces is 
substituted. However, either cr_seq.count or bs_seq.count should be nonzero 
(i.e., both should not be zero). 

bs_seq 

is the output character sequence to be substituted for a backspace character. 
If count is zero, a carriage return and the appropriate number of spaces are 
substituted. However, either bs_seq.count or cr_seq.count, should be nonzero 
(i.e., both should not be zero). 

tab_seq 

is the output character sequence to be substituted for a horizontal tab. If 
count is zero, the appropriate number of spaces is substituted. 

vt_seq 

is the output character sequence to be substituted for a vertical tab. If count 
is zero, no characters are substituted. 

ff_seq 

is the output character sequence to be substituted for a formfeed. If count is 
zero, no characters are substituted. 

printer_on 

is the character sequence to be used to implement the printer_on control 
operation. If count is zero, the function is not performed. 

printer_off 

is the character sequence to be used to implement the printer_off control 
operation. If count is zero, the function is not performed. 

red_ribbon_shift 

is the character sequence to be substituted for a red-ribbon-shift character. 
If count is zero, no characters are substituted. 

black_ribbon_shif t 

is the character sequence to be substituted for a black-ribbon-shift character. 
If count is zero, no characters are substituted. 

end_of_page 

is the character sequence to be printed to indicate that a page of output is 
full. If count is zero, no additional characters are printed, and the cursor is 
left at the end of the last line. 
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escapejength 

is the number of output escape sequences in each of the two escape arrays. 
not_edited_escapes 

is an array of escape sequences to be substituted for particular characters if 
the terminal is in " A edited" mode. This array is indexed according to the 
indicator found in the corresponding output conversion table (see the 
description of the set_output_conversion order above). 

edited_escapes 

is an. array of escape sequences to be used in edited mode. It is indexed in 
the same. fashion as not_edited_escapes. 

input_escapes 

is a string of characters each of which forms an escape sequence when 
preceded by an escape character. 

input_results 

is a string of characters each of which is to replace the escape sequence 
consisting of an escape character and the character occupying the corresponding 
position in input_escapes. 

set_term_type 

sets the terminal type associated with the channel to one of the types defined in 
the terminal type table. The info_ptr should point to the following structure 
(declared in set_term_type_info.incl.pll): 

del 1 set_term_type_i nf o aligned based (sttip), 

2 version fixed bin, 

2 name char (32) unaligned, 

2 flags, 

3 send_ini tial_str ing bit(l) unaligned, 
3 set_modes bit(l) unaligned, 

3 i gnore_l i ne_type bit(l) unaligned, 
3 mbz ~ bit (33) ; 

where: 
version 

is the version number of the above structure. It must be 1. 
name 

is the name of the terminal type to be set 
send_initial_string 

is "l"b if the initial string for the terminal type is to be transmitted to the 
terminal; otherwise, it is "0"b. 
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set_modes 

is 'T'b if the default modes for the terminal type are to be set; otherwise, it 
is "0"b. 

ignore_line_type 

is "l"b if the terminal type to be set need not be compatible with the line 
type; otherwise, it is "0"b. 

mbz 

must be "0"b. 
set_wakeup_table 

specifies a wakeup table, i.e., a set of wakeup characters that controls the 
dispatching of input wakeups. The wakeup table operates in conjunction with 
wake_tbl mode. The wakeup table has no effect until wake_tbl mode is enabled. 
Once enabled, the standard method of generating input wakeups (normally one 
wakeup for each line) is suspended. Thereafter, wakeups are only generated when 
wakeup characters are received or when the buffer gets too full. The wakeup 
table cannot be changed while wake_tbl mode is enabled. The info_ptr should 
point to the following structure (declared in set_wakeup_table_info.incl.pll): 

del swt_infop ptr; 

del swt_i nf o_vers i on_l fixed bin static options (constant) init (1) ; 

del 1 swt_info aligned based (swt_infop), 
2 version fixed bin, 
2 new_table like wakeup_table, 
2 old_table like wakeup_table; 

del wakeup__tab lep ptr; 

del 1 wakeup_table aligned based (wakeup_tab 1 ep) , 
2 wakejnap (0:127) bit (1) unal, 
2 mbz bit (16) unal ; 

where: 
version 

is the version number of this structure. (Input). It must be 1. 

new_table 

is the wakeup table to set. (Input) 

old_table 

is set to the value of the current wakeup table that is being replaced. 
(Output). If no current wakeup table exists, all entries are set to "0"b. 
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is an array having one entry for each character in the ASCII character set. 
(Input). A value of "l"b defines a wakeup character. All other entries must 
be "0"b. If all entries are "0"b, the current wakeup table, if any, is deleted. 

mbz 

must be "0"b. (Input) 

The primary application for the wakeup table mechanism is to reduce overhead 
incurred by text editors, such as qedx, while in input mode. While in input 
mode, a user process must wake up for each line of input even though no 
processing is immediately required. In wake_tbl mode, a process is only awoken 
when input mode is exited or a large amount of input has been accumulated. 
However, since wake_tbl mode causes more input to be buffered in ring 0 than 
before, a quit signal is likely to discard more input than before. If a user does 
not wish to lose input, he simply should avoid quitting while in input mode. 

If a user does quit out of input mode, he does not remain in wake_tbl mode 
(under normal circumstances). The default modes established by the standard quit 
handler include A wake_tbl. A start command restores wake_tbl mode. 

LIST OF MISCELLANEOUS CONTROL ORDERS 

copy_meters 

causes the current cumulative meters associated with the channel to be copied to 
un wired storage, so that the statistics for the channel can be determined both for 
the life of the system and for the current dialup. This order can only be issued 
by the "owning" process (normally the initializer). The info_ptr should be null. 

get_even t_channel 

returns the identifier of the ipc_ event channel associated with the channel. The 
info_pointer should point to a fixed bin (71) aligned quantity into which the 
channel identifier is stored. If the switch is not yet open and the set_event_channel 
order has not been given, the result is zero. 

This control order, which replaces the evenMnfo control order, is accepted with 
the switch open or closed. For more information on event management, see the 
set_event_channel control order. 

quit_disable 

causes quit signal processing to be disabled for this device. 
quit_enable 

causes quit signal processing to be enabled for this device. (Quit signal processing 
is initially disabled.) 
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read_status 

tells whether or not there is any type-ahead input waiting for a process to read. 
The info_ptr should point to the following structure (defined in 
tty_read_status_info.incl.pll), which is filled in by the call: 

del 1 tty_read_status_i nf o aligned based, 

2 event_channel fixed bin (71) , 

2 i nput_pendi ng bit (1); 

where: 

event_channel 

is the event channel used to signal the arrival of input. 

input_available 

indicates whether input is available. 
"0"b no input 
"l"b input 

send_initial_string 

transmits an initialization string to the terminal in raw output (rawo) mode. Due 
to the use of raw output mode, the string must comprise character codes 
recognized by the terminal. If the info_ptr is null, the initial string defined for 
the terminal type is used. Otherwise, the info_ptr should point to the following 
structure: 

del 1 send_i n i t i a l_str i ng_i nf o aligned, 

2 version fixed bin, 

2 initial string char(512) varying; 

where: 
version 

is the version number of the above structure. It must be 1. 

initial_string 

is the initial string to be sent. 

set_def ault_modes 

sets the modes to the default modes for the terminal type. 
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set_event_channel 

specifies the ipc_ event channel that receives wakeups for this attachment. 
Wakeups are received for input available, output completed, and state changes such 
as hangups and quits. The channel can be event wait or event call. If it is event 
call, the -no_block control argument must be present in the attach description for 
correct operation. 

The info_pointer should point to a fixed bin (71) aligned quantity containing a 
valid ipc_ channel identifier. No check for the validity of the channel is made. 
If the channel is invalid, incorrect operation results. 

If this control order is not given before the opening of the switch, tty_ attempts 
to allocate a fast event channel. Fast event channels cannot be converted to call 
channels and receive no associated message. If tty_ cannot allocate a fast channel, 
an ordinary event wait channel is created and used. This control order is accepted 
while the switch is closed or open. If the switch is open, the new channel 
replaces the old one. 

start 

causes a wakeup to be signalled on the event channel associated with this device. 
This request is used to restart processing on a device whose wakeups may have 
been lost or discarded. 



stores the answerback identifier of the terminal for later use by the process. The 
info_ptr should point to a char(4) variable that contains the new identifier. 



returns information about the terminal. The info_ptr should point to the 
following structure (declared in terminal_info.incl.pll): 



store_id 



terminal_info 



del 1 



termi nal_i nf o 
2 version 
2 id 

2 term_type 
2 1 i ne_type 
2 baud_rate 
2 reserved (h) 



al i gned, 

f i xed bin, 

char (k) una 1 i gned , 

char (32) unaligned, 



fixed bin, 
fixed bin, 
fixed bin; 



where: 



version 
is 



the version number of the above structure. (Input). It must be 1. 



id 



is 



the terminal identifier derived from the answerback. (Output) 



term_type 

is the terminal type name. (Output) 
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is the line type number. (Output) 

baud_rate 

is the baud rate at which the terminal is running. (Output) 

reserved 

is reserved for future use. 

write_status 

tells whether or not there is any write-behind output that has not been sent to 
the terminal. The info_ptr should point to the following structure, which is filled 
in by the call: 

del 1 i nf o_structure aligned, 

2 ev_chan fixed bin (71), 

2 output_pend i ng bit(l); 

where: 
ev_chan 

is the event channel used to signal the completion of output. 

output_pending 

indicates whether output is pending. 
"0"b no output 
"l"b output 

MODES OPERATION 

The modes operation is supported when the I/O switch is open. The recognized 
modes are listed below. Some modes have a complement indicated by the circumflex 
character (~) that turns the mode off. For these modes, the complement is displayed 
with the mode. Normal defaults are indicated for those modes that are generally 
independent of terminal type. The modes string is processed from left to right; thus, 
if two or more contradictory modes appear within the same modes string, the 
rightmost mode prevails. 

LIST OF MODES 

8bit, A 8bit 

causes input characters to be received without removing the eighth (high-order) 
bit, which is normally interpreted as a parity bit. This mode is valid for HSLA 
channels only. (Default is off.) 

blk_xfer, A blk_xfer 

specifies that the user's terminal is capable of transmitting a block or "frame" of 
input all at once in response to a single keystroke. The system cannot handle 
such input correctly unless blk_xfer mode is on and the set_framing_chars order 
has been issued. (Default is off.) 
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breakall, A breakall 

enables a mode in which all characters are assumed to be break characters, 
making each character available to the user process as soon as it is typed. This 
mode only affects get_chars operations. (Default is off.) 

can, A can 

performs standard canonicalization on input. (Default is on.) 

can_type=overstrike, can_type=replace 

specifies the method to be used to convert an input string to canonical form. 
Canonicalization is only performed when the I/O switch is in "can" mode. 
(Default is can_type=overstrike.) 

capo, A capo 

outputs all lowercase letters in uppercase. If edited mode is on, uppercase letters 
are printed normally; if edited mode is off and capo mode is on, uppercase 
letters are preceded by an escape (\) character. (Default is off.) 

crecho, A crecho 

echoes a carriage return when a line feed is typed. This mode can only be used 
with terminals and line types capable of receiving and transmitting simultaneously. 

ctl_char, A ctl_char 

specifies that ASCII control characters that do not cause carriage or paper motion 
are to be accepted as input, except for the NUL character. If the mode is off, 
all such characters are discarded. (Default is off.) 

default 

is a shorthand way of specifying erkl, can, ~rawi, ^rawo, ~wake_tbl, and esc. The 
settings for other modes are not affected. 

echoplex, A echoplex 

echoes all characters typed on the terminal. The same restriction applies as for 
crecho; it must also be possible to disable the terminal's local copy function. 

edited, A edited 

suppresses printing of characters for which there is no defined Multics equivalent 
on the device referenced. If edited mode is off, the 9-bit octal representation of 
the character is printed. (Default is off.) 

erkl, A erkl 

performs "erase" and "kill" processing on input. (Default is on.) 
esc, A esc 

enables escape processing on all input read from the device. (Default is on.) 
force 

specifies that if the modes string contains unrecognized or invalid modes, they are 
to be ignored and any valid modes are to be set. If force is not specified, 
invalid modes cause an error code to be returned, and no modes are set. 
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fulidpx, A fulldpx 

allows the terminal to receive and transmit simultaneously. This mode should be 
explicitly enabled before enabling echoplex mode. 

hndlquit, A hndlquit 

echoes a newline character and performs a resetread of the associated stream when 
a quit signal is detected. (Default is on.) 

iflow, A iflow 

specifies that input flow control characters are to be recognized and /or sent to 
the terminal. The characters must be set before iflow mode can be turned on. 

init 

sets all switch type modes off, sets line length to 50, and sets page length to 
zero. 

If echo, A If echo 

echoes and inserts a line feed in the user's input stream when a carriage return is 
typed. The same restriction applies as for crecho. 

iin, A n 

specifies the length in character positions of a terminal line. If an attempt is 
made to output a line longer than this length, the excess characters are placed on 
the next line. If ^11 is specified, line length checking is disabled. In this case, if 
a line of more than 255 column positions is output by a single call to 
iox_$put_chars, some extra white space may appear on the terminal. 

no_outp, A no_outp 

causes output characters to be sent to the terminal without the addition of parity 
bits. If this mode and rawo mode are on, any 8-bit pattern can be sent Lo the 
terminal. This mode is valid for HSLA channels only. (Default is off.) 

oddp, A oddp 

causes any parity generation that is done to the channel to assume odd parity. 
Otherwise, even parity is assumed for line types other than 2741 and 1050. This 
mode is valid for HSLA channels only. (Default is off.) 

oflow, A oflow 

specifies that output flow control characters are to be recognized when sent by 
the terminal. The characters and the protocol to be used must be set before 
oflow mode can be turned on. 
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plN, A pl 

specifies the length in lines of a page. When an attempt is made to exceed this 
length, a warning message is printed. When the user types any break character, 
the output continues with the next page. The warning message is normally the 
string "EOP", but can be changed by means of the set_special control order. The 
string is displayed on a new line after N consecutive output lines are sent to the 
screen (including long lines that are folded as more than one output line). To 
have the end-of-page string displayed on the screen without scrolling lines off the 
screen, N should be set to one less than the page length capability of the screen. 
However, if the end-of-page string is a null string, output stops at the end of 
the last line of the page or screen and N should be the actual page length 
capability of the screen.. If "pi is specified, end-of-page checking is disabled. 
(See scroll mode below.) 

polite, A polite 

does not print output sent to the terminal while the user is typing input until the 
carriage is at the left margin, unless the user allows 30 seconds to pass without 
typing a newline. (Default is off.) 

prefixnl, A prefixnl 

controls what happens when terminal output interrupts a partially complete input 
line. In prefixnl mode, a newline character is inserted in order to start the 
output at the left margin; in "prefixnl mode, the output starts in the current 
column position. Polite mode controls when input may be interrupted by output; 
prefixnl controls what happens when such an interruption occurs. (Default is on.) 

rawi, A rawi 

reads the data specified from the device directly without any conversion or 
processing. (Default is off.) 

rawo, A rawo 

writes data to the device directly without any conversion or processing. (Default 
is off.) 

red, A red 

sends red and black shifts to the terminal, 
replay, A replay 

prints any partial input line that is interrupted by output at the conclusion of the 
output, and leaves the carriage in the same position as when the interruption 
occurred. (Default is off.) 

scroll, A scroll 

specifies that end-of-page checking is performed in a manner suited to scrolling 
video terminals. If the mode is on, the end-of-page condition occurs only when 
a full page of output is displayed without intervening input lines. The mode is 
ignored whenever end-of-page checking is disabled. (Default is off.) 
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tabecho, A tabecho 

echoes the appropriate number of spaces when a horizontal tab is typed. The 
same restriction applies as for crecho. 

tabs, A tabs 

inserts tabs in output in place of spaces when appropriate. If tabs mode is off, 
all tab characters are mapped into the appropriate number of spaces. 

vertsp, A vertsp 

performs the vertical tab and formfeed functions, and sends appropriate characters 
to the device. Otherwise, such characters are escaped. (Default is off.) 

wake_tbl, A wake_tbl 

causes input wakeups to occur only when specified wakeup characters are received. 
Wakeup characters are defined by the set_wakeup_table order. This mode cannot 
be set unless a wakeup table has been previously defined. 

NOTES 

The status code error_tabie_$action_not_performed is returned by the prinler_on and 
printer_off control operations if the special characters table currently in effect 
indicates that this terminal cannot perform the printer_on or printer_off operation. 
The status code error_table_$no_table is returned by the get_input_translation, 
get_output_translation, get_input_conversion, get_output_conversion, and get_special control 
orders if the specified table does not exist. A code of zero is returned otherwise. 

To assist the user in determining how to alter the tables described above, the 
following paragraphs provide a summary of the processing of input and output strings 
in ring 0. 

INPUT PROCESSING 

Translation The characters are translated from the terminal's code to ASCII, using 
the input_translation table. If there is no input_translation table, this step is omitted. 



Canonical ization 

The input string is rearranged (if necessary) into canonical form. 



Editing 

Performs erase and kill processing. 
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Break and escape processing 

The characters in the input string are looked up in the input_conversion table and 
treated accordingly. If a character is preceded by an escape character (as determined 
from the table), it is looked up in the input_escapes array in the special_chars table 
and, if found, replaced by the corresponding character from the input_results array. 

OUTPUT PROCESSING 



Capitalization 

Lowercase letters are replaced by uppercase for terminals in capo mode; uppercase 
letters are prefixed by escape characters if appropriate. 



Formatting 

The characters in the output string are looked up in the output_conversion table 
described above. Carriage-movement characters are replaced by sequences found in the 
special_chars table, followed by delay characters if so indicated by the delay table. 
Ribbon-shift characters are likewise replaced by appropriate sequences. Any character 
whose indicator in the output_conversion table is greater than 16 is replaced by the 
(indicator-16)th sequence in either the not_edited_escapes or edited_escapes array in 
the special_chars table. 



Translation 

The result of step 2 is translated from ASCII to the terminal's code, using the 
output_translation table. If there is no output_translation table, this step is omitted. 

CONTROL OPERATIONS FROM COMMAND LEVEL 

Some control operations can be performed from the io_call command, as follows: 
io_call control switch_name order_arg 
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ARGUMENTS 

switch_name 

is the name of the I/O switch. 

order_arg 

can be any control order described above under "Control Operation" that can 
accept a null info_ptr, as well as read_status, write_status, terminal_info, and the 
following (which must be specified as shown): 

store_id id 

where id is the new answerback string. 

set_term_type type {-control_args} 

where type is the new terminal type and -control_args can be any of 
-initial_string (-istr), -modes, and -ignore_line_type. 

set_line_type line_type 

where line_type is the new line type= 

line_length N 

where N is the new line length. 

The following control orders can be used as active functions: 

[io_call control switch_name read_status] 

returns true if input is available; otherwise, false. 

[io_call control switch_name write_status] 

returns true if output is pending; otherwise, false. 

[io_call control switch_name terminal_info terminal_type] 
returns the current terminal type. 

[io_call control switch_name terminal_info baud] 
returns the baud rate. 

[io_call control switch_name terminal_info id] 
returns the terminal identifier (answerback). 

[io_call control switch_name terminal_info line_type] 
returns the current line type. 
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Name: tty printer 

The tty_printer_ I/O module performs stream I/O to a standard terminal (e.g., 
TN1200, ROSY, Diablo, VIP7760, or IBM3270 printer) to make it operate as a remote 
printer. The hardware options currently supported are defined by the control 
arguments described below. 

The tty_printer_ I/O module can also be used to direct its stream I/O through the 
syn_ I/O module to another I/O switch (e.g., user_i/o or to a file switch through 
vfilej. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. It is normally attached through the remote_printer_ 
I/O module, and all attach options are passed through remote_printer_ to tty_printer_. 

ATTACH DESCRIPTION 

tty_printer_ -control_args 

CONTROL ARGUMENTS 

The following control arguments are optional, with the exception of -comm, -device, 
and -tty: 

-auto_call N 

specifies the phone number, N, to be called via the automatic call unit on the 
specified communications channel. 

-comm STR 

uses the communications I/O module specified by STR. Normally, STR is either 
tty_ or syn_. 

-device STR 

attaches the switch as the device type specified by STR. STR is normally printer 
or teleprinter. 

-horizontal_tab, -htab 

specifies that horizontal tab characters are to be sent to the device. 

-physical_line_length N, -pll N 

specifies the physical line length, N, of the output device. 

-terminal_type STR, -ttp STR 

STR specifies the terminal type whose conversion, translation, and special tables 
defined in the user or system terminal type table (TTT) are used to convert and 
translate input and output to and from the device. If not specified, the default 
terminal type is used. 
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-tty STR 

defines the target communications channel to be STR, where STR is an I/O 
switch name if the communications I/O module is syn_. 

-vtab 

specifies that vertical tab characters are to be sent to the device. 
OPEN OPERATION 

The tty_printer_ I/O module supports stream_input, stream_output, and 
stream_input_output opening modes. 

PUT CHARS OPERATION 

The put_chars entry passes the data directly to the communications I/O module 
without any conversion. 

GET CHARSIGET LINE OPERATION 

The get_chars and get_line entries - pass the operation directly to the communications 
I/O module. 

CONTROL OPERATION 

This I/O module passes all undefined control operations to the communications I/O 
module. In addition, it supports the control operations listed below. Unless otherwise 
specified, there are no input control structures. 

select_device 

selects the device characteristics for which oulpul is next directed. The device is 
the one associated with the I/O switch by the -device option at attachment. The 
input structure is of the form: 

del device char (32) ; 

runout 

transmits any data stored in the output buffer. 
hangup_proc 

sets up a specified event call channel to be signalled over, and a procedure to be 
called, if the communications channel hangs up. The hangup_proc input structure 
has the following form: 

del 1 hangup_proc aligned, 

2 entry entry variable, 

2 datap ptr, 

2 prior fixed bin? 
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where: 
entry 

is the entry to call when a hangup is detected, 
datap 

is a pointer to data for the hangup procedure, 
prior 

is the ipc_ event call priority to be associated with hangup notification. 

reset 

sets the A edited mode of output conversion and enables the tabs and vertsp modes 
if required by attachment options. 

get_error_count 

returns the current count of errors detected since attachment The input structure 
is of the form: 

del error_count fixed bin; 

hangup 

is used to hang up the device communications connection. This control operation 
is trapped if the communications I/O module is syn_, otherwise it is passed on. 

MODES OPERATION 

This I/O module passes all modes operations to the communications I/O module. 
NOTES 

This I/O module is normally attached through a remote device I/O module (e.g. 
remote_printer_ or remote_teleprinter_.) Attachment to tty_printer_ is specified in the 
remote_device attach description by "-terminal tty_printer_" along with any attach 
options listed above. The -device attach option is supplied by the remote_device I/O 
module. 
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Name: vfile 

This I/O module supports I/O from/to files in the storage system. All logical file 
types are supported. 

Entry points in this module are not called directly by users; rather, the module is 
accessed through the I/O system. See the Programmer's Reference Manual for a 
general description of the I/O system and a discussion of files, respectively. 

ATTACH DESCRIPTION 

The attach description has the following form: 

vfile_ path {-control_args} 



ARGUMENTS 
path 

is the absolute or relative pathname of the file. 
CONTROL ARGUMENTS 

are arranged below according to the file types for which they are appropriate. The 
categories following are: any file type, any file type except indexed, blocked files, 
indexed files, sequential files, and unstructured files. 

For any type of file, control_args can be chosen from the following: 

-extend 

specifies extension of the file if it already exists. The position is normally set at 
the end of file. This control argument is only meaningful with openings for 
output or input_output; otherwise, it is ignored. 

-old 

indicates that a new file is not to be created if an attempt is made to open a 
nonexistant file for output, input_output, or update. If the file does not exist, the 
user is informed of this at open time. 

For any file type except indexed, control_args can be chosen from the following: 

-append 

in input_output openings, this control argument causes put_chars and write_record 
operations to add to end of file instead of truncating when the file position is 
not at end of file. Also the position is initially set to beginning of file, and an 
existing file is not truncated at open. 
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restricts the file to a single segment. If specified, an attempt to open a 
multisegment file or to expand a file beyond a single segment is treated as an 
error. 

For blocked files, control_args can be chosen from the following: 
-share {N} 

allows a file to be open in more than one process at the same time, even though 
not all openings are for input. (See "Multiple Openings" below.) If specified, N 
is the maximum time in seconds that this process waits to perform an operation 
on the file. A value of -1 means the process may wait indefinitely. The default 
value of N is 1. 

-blocked {N} 

specifies attachment to a blocked file. If a nonempty file exists, N is ignored and 
may be omitted. Otherwise, N is used to set the maximum record size (bytes). 

-no_end 

permits positioning beyond end of file (last record or byte written) and then 
appending to the file without encountering an error. Instead, the end of file 
position is advanced leaving any intervening bytes zero, or leaving record positions 
beyond the previous end of file with the appearance of being logically deleted 
(see "Logically Absent Records" below). 

For indexed files, control_args can be chosen from the following: 

-share {N} 

see the -share control argument under blocked files above. 
-dup_ok 

indicates that the creation of duplicate keys is permitted (see "Duplicate Keys" 
below). 

-exclusive 

causes the exclusion of all shared references in other openings for the duration. of 
this opening. The file must be opened for modification. This control argument 
conflicts with the -share control argument. Shared readers in other openings are 
otherwise excluded only while an update operation is in progress, or while the file 
has been explicitly locked to exclude readers via the set_file_lock order. 

-stationary 

causes newly created records to be of the stationary type, and forces vfile_ to 
maintain a reference count during the addition and removal of keys from such 
records. The use of this control argument is recommended for applications with 
multiply keyed records, or when record level synchronization is required (see 
"Multiply Keyed Records" and "Record Locks" below). 
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-transaction tcf_sw, -trans tcf_sw 

indicates that all operations on this switch are performed within transactions 
associated with a control file attached to the I/O switch named tef_sw. The file 
must be indexed with stationary type records (see the transaction_call command 
and transaction_call_ subroutine in the Transaction Processing manual for more 
information). 

For unstructured files, control_args may be chosen from the following: 
-header {N} 

indicates that a header is expected in an existing file, or is to be created for a 
new file. If a header is specified, it contains an optional identifying number that 
effectively permits user-defined file types. If N is given and the file exists, the 
file identifier must be equal to N; a new file takes the value of N, if given, as 
its identifier. The header is maintained and becomes invisible only with the 
explicit use of this control argument. 

-no_trunc 

indicates that a put_chars order into the middle of an unstructured file 
(stream_input_output) is permitted, and no truncation is to occur in such cases. 
This control argument also prevents the truncation of an existing file at open, and 
in stream_input_output openings causes the next byte position to be initially set to 
beginning of file. 

-no_end 

see the -no_end control argument under blocked files above. 

The -extend, -append, and -no_trunc control arguments conflict; only one of these 
may be specified. 

To form the attach description actually used in the attachment, the pathname is 
expanded to obtain an absolute pathname. 

OPENING AND ACCESS REQUIREMENTS 

All opening modes are supported. For an existing file, the mode must be compatible 
with the file type. The mode must be compatible with any control arguments given in 
the attach description. 

If the opening is for input only, only read access is required on the file. In all other 
cases, rw access is required on the file. 

MODES OPERATION 

This operation is not supported. 



11/86 



3-222 



AG93-05A 



vfile_ 



vfile_ 



CONTROL OPERATION 

The following orders are supported by the vfile_ I/O module. The orders in the first 
column are those most often used. The remaining orders include various features of 
indexed files that require somewhat more knowledge of internal file structure than is 
expected of most users. The letters following the names of the orders indicate the 
type of file for which the orders apply. The letters and their meanings are: A - any 
file, B - blocked file, I - indexed file, S - sequential file, and U - unstructured file. 



add_key 


I 


read_position 


B,S,U 




delete_key 


I 


reassign_key 


I 


* 


error_status 


I,S 


record_status 


B,I,S 




exclude 


I 


seek_head 


I 


* 


file_status 


A 


select 


I 




getjcey 


I 


set_file_lock 


I 




max_rec_len 


B 


set_wait_time 


I 




min_block_size 


I 


truncate 


B,S,U 





Detailed descriptions of the orders are given, in alphabetical order, at the end of the 
general discussion. 

CONTROL OPERATIONS FROM COMMAND LEVEL 

All control orders can be performed using the io_call command. The general format 
is: 

io_call control switch_name order {opt i onal__args} 

ARGUMENTS 
order 

is any of the control orders supported by vfile_, or the short name of the 
control order, if it has one. 

optional_args 

are required for certain orders as indicated in the descriptions of the orders. 
MULTIPLE OPENINGS 

It is possible to have or attempt to have multiple openings of the same file, that is, 
to have two or more open I/O switches attached to the same file. These switches 
might be in the same process or in different processes. With respect to the effects of 
multiple openings, the various opening modes can be divided into four classes 
(explained below). Multiple openings in which the opening modes are in more than 
one class are invalid, as are multiple openings within certain classes. The vfile_ I/O 
module prevents some cases of multiple opening. In these cases, error_table_$file_busy 
is returned by the open order. In cases where an invalid multiple opening does occur, 
I/O operations cause unpredictable errors in the processes involved, and the contents 
of the files may be damaged. 
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The classes of multiple openings are: 

1. Openings for input without the -share control argument. 

Any number of openings in this class are allowed. The existence of an opening 

in this class never causes damage to the file. When this class of opening is 

attempted, the existence of all class 2 and 3 openings and some class 4 
openings will be detected for structured files. 

2. Openings for output or input_output without the -extend control argument. 

Only one opening is allowed. The existence of another opening is never 
detected when this class of opening is attempted. The file is simply replaced 
by an empty file of the appropriate type. If the file was already open with 
an opening of any class except class 1, the contents of the new file will 
probably be damaged. 

3. Openings for update without the -share control argument and for output or 
input_output without the -share control argument and with the -extend control 
argument. 

Only one opening of this class is allowed. For structured files, multiple 
openings within the class are detected. An invalid multiple opening involving 
an opening of this class and other openings of class 4 may be detected. If 
not, the only effect is that the class 3 opening locks the file for the entire 
opening. 

4. Openings with the -share control argument 

Any number of openings of this type are allowed. When a process performs 
an update on the file, the file is locked. Other processes attempting an 
operation while the file is locked wait up to the limit specified by N in the 
-share control argument or from the last set_wait_time order. If the operation 
is not carried out because of the limit N, the code error_table_$file_busy is 
returned. 

Two codes pertain only to class 4 openings: error_table_$asynch_deletion and 
error_table_$asynch_insertion. The first is returned when there is an attempt to 
reference a record located by the previous operation, but the record has been 
deleted in some other opening. The second is returned by write_record when a 
record with the key for insertion (defined by a seek_key order) has already 
been inserted (by some other opening). 

The code error_table_$asynch_change is returned on a subsequent reference to 
an item previously referenced in the same transaction, if an asynchronous 
change is detected. 
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INCONSISTENT FILES 

The code error_table_$bad_file (terminal message: "File is not a structured file or is 
inconsistent") may be returned by operations on structured files. It means that an 
inconsistency has been detected in the file. Possible causes are: 



OBTAINING FILE INFORMATION 

The type and various statistics of any of the four vfile_ supported file structures 
(blocked, indexed, sequential, and unstructured) may be obtained with the vfile_status 
command or vfile_status_ subroutine. 

The remainder of this discussion will treat each of the four file structures separately. 
BLOCKED FILES 

The following paragraphs describe exceptions and provide information applicable to 
blocked files. For general information on the subjects mentioned here, see the 
Programmer's Reference Manual. 



Position Operation 

In addition to the standard iox_ positioning, another type of positioning is available 

with filpc that nrp rvnen fnr tnrmt irmiit Qiitmit c\r imHatp Wh**n the tvr»A armimpnt 

of the iox_$position entry point is 2, this specifies direct positioning to the record 
whose ordinal position (0, 1, 2, ...) is given. The zero position is just beyond the file 
header. 



Write Operation 

The write operation is supported in files open for update. The effect is to append a 
record to the file or replace the next record, depending on the next record position. 



Rewrite Operation 

No record may be written over with a record whose length exceeds the maximum 

record length of the file. Attempting to do so causes the code, error_table__$long^record, 
to be returned. 



1. 



The file is not a structured file of the required type. 



2. 



A program accidentally modified some words in the file. 
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Delete Operation 

Deletions are supported by marking the current record as logically deleted. If the last 
record is deleted, the end of file position is moved back to just beyond the previous 
nondelcted record. 



Logically Absent Records 

Within the limits of efficiency imposed by the choice of implementation, the concept 
of deletion is interchangeably defined for the different types of files. In certain 
situations, however, it is necessary to distinguish between the various ways in which a 
record may appear to be absent from a file. 

In a blocked file the space occupied by deleted records is reusable. The appearance of 
a deletion is less absolute than in a sequential file, for example. For the purpose of 
this discussion, records implicitly allocated when the file is extended with the -no_end 
attach control argument are equivalent to those that have been deleted. When a record 
is deleted, its position is reserved and marked as logically absent. The end of file 
position is maintained just beyond the last nondeleted record. 

Records that have been marked as logically absent are made invisible to the user in 
most situations, so that the distinction between logical and absolute deletion can often 
be disregarded. The exception to this is that the position operation and the get_key 
and seek_head orders permit one to locate a logically deleted record without regard to 
the logical presence or absence of records. Operations that reference the current 
record treat its being logically absent as an error, returning the code error_table_$no_record. 
Operations referencing the length or contents of the next record, on the other hand, 
do not treat its being logically absent as an error, but scan sequentially for the next 
instance of a nondeleted record or end of file. Records are scanned in ascending 
order, except immediately following a successful backward position skip operation, in 
which case scanning is done in reverse order. 



Interrupted Openings 

If a process opens a file and terminates without closing the file, the file may be left 
in an intermediate state that prohibits normal I/O operations on the file. The 
exception is openings for input only. In general, the file's bit count and record count 
will not be correct. This condition is detected at a subsequent open, and either the 
file is automatically adjusted or (if the opening is input only) the code 
error_table_$file_busy is returned. 

Any type of file may be properly adjusted with the vfile_adjust command if an 
interrupted opening has occurred. 

INDEXED FILES 

The following paragraphs describe exceptions and provide information applicable to 
indexed files. For general information on the subjects mentioned, see the Programmer's 
Reference Manual. 
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Position Operation 

The type 2 position operation is not supported for indexed files. 



Rewrite Operation 

For indexed files, if the current record is not of the stationary type, and the current 
position is "outside" the index (e.g., after a delete_key order or use of the 
record_status order with the locate switch), then the new record length must be small 
enough to fit in the old record without reallocation; otherwise, the code 
error_table_$long_record is returned. 



Delete Operation 

In an indexed file, stationary records having multiple keys (reference count>l) are 
deleted by being marked as logically deleted, until a later time when garbage collection 
automatically takes place (see "Logically Absent Records" below). 



Logically Absent Records 

Records that have been marked as logically absent are made invisible to the user in 
most situations, so that the distinction between logical and absolute deletion can often 
be disregarded. The exception to this is that the position order permits one to locate 
a logically deleted record without regard to the logical presence or absence of records. 
Operations that reference the current record treat its being logically absent as an 
error, returning the code error_tab!e_$no_record. Operations referencing the length or 
contents of the next record, on the other hand, do not treat its being logically absent 
as an error, but scan sequentially for the next instance of a nondeleted record or end 
of file. Records are scanned in ascending order, except immediately following a 
successful backward position skip operation, in which case scanning is done in reverse 
order. 

For records that are not of the stationary type, or for some cases of stationary 
records, the effect of a deletion is absolute, and the record's storage is immediately 
recovered. In the case of multiply keyed stationary records (reference count>l), 
however, the record is logically deleted. The presence of such records is automatically 
masked until garbage collection occurs. This behavior ensures that there are never 
inconsistencies of the form where an index entry refers to a record that is no longer 
valid (see "Multiply Keyed Records" below). 

Garbage collection of keys belonging to logically deleted records takes place 
automatically upon their detection in a file opened for modification. Only when the 
last reference has been removed is the body of a logically deleted record entirely 
freed, so that every bit of its storage can be reused. 
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In shared openings, garbage collection of the record's last key and stationary header is 
postponed until the effective collection delay time since the logical deletion has 
elapsed. This is done to ensure that any passive reference to the record prior to its 

* deletion can find the record header afterwards and detect the asynchronous change. 
The delay should be set by the user, with the set_wait_time order, to a duration that 
exceeds the maximum time a transaction (or a single vfile_ operation) can be in 

* progress or until an intermediate call is made to transaction_call_$status with the 
verify option. 

Scanning over logically absent records in an indexed file is subject to one additional 
constraint not applicable to blocked files. Specifically, after a successful seek_head or 
get_key order with rel_type=0 (head must match), scanning is limited to the last key 
whose head matches that previously specified. This only applies to an operation that 
references the next record in the immediately following operation. 

A temporary form of logical deletion is also available through the use of the select 
and exclude orders with indexed files. Records made to appear absent through these 
orders are not altered in any way, so there is certainly no reuse of storage in this 
case. Except for leaving the file statistics unchanged, this form of logical deletion may 
be regarded as absolute, insofar as all subsequent operations (including position) behave 
as if such logically absent records and their keys never existed in the first place. 



Duplicate Keys 

By default, the vfile_ I/O module prevents the user from associating a single key with 
more than one record in the same indexed file. This restriction is removed when the 
-dup_ok control argument is used or if the file's statistics indicate that duplicate keys 
are already present. 

Duplicate keys can be created via either the write_record operation or the add_key or 
record_status control orders. When duplications are permitted, the key for insertion is 
defined as the key of the current record, if it exists. 

With this extension, the notion of an "index entry" becomes more basic than that of a 
single key in the index. An index entry is an association between a string of 
characters (key) and a number (record descriptor). 

Index entries are ordered by key. Within multiple occurrences of the same key, the 
order is identical to the order in which the entries were created. A seek_key or 
seek_head order locates the first instance of a set of duplicate keys. A write_record 
order advances the file position beyond the last instance of the key for insertion, if 
the key already exists in the index. 

The next record position is best thought of as corresponding to the next index entry. 
Orders that can advance the next record position (i.e., read_record, rewrite_record, 
get_key, and position with a type argument of 0) permit one to locate intermediate 

instances of duplicate keys. 
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The vfile_ I/O module allows any number of keys to be associated with a given 
record in an indexed file through the use of the add_key control order. In 
conjunction with the use of duplicate keys, arbitrary many-to-many relationships can 
be established between keys and records. The appearance of each of a record's keys is 
completely independent of the existence of any other keys, i.e., there is no distinction 
between primary and secondary keys. 

The orders delete_key and reassign_key permit keys to be removed and reassigned 
from one record to another. Information about which and how many keys belong to 
a given record may be obtained with the get_key and record_status orders. 

When duplicate keys are allowed, it may be necessary to specify more than one key in 
order to uniquely identify a record. The use of successive select orders permits one to 
achieve this effect by progressively narrowing down a cross section of the file to be 
made visible. Conversely, the exclude order permits records to be found by the 
process of elimination. 

File statistics are maintained giving the number of keys, number of duplicate keys, and 
number of records separately, as well as the total length of keys, and the total length 
of duplicate keys. With regard to these values, the count of duplications does not 
include the first instance of a key. A count of keys is maintained for each record as 
an option, specified by the -stationary control argument 

In general, when multiple keys are present in a file subject to random updates, it is 
recommended that the -stationary control argument be used. Otherwise it is the user's 
responsibility to maintain a consistent relationship between the index and the records 
when records are either deleted or reallocated. This problem can be avoided when 
stationary records are used under the -stationary control argument 

Stationary records have the property that the descriptor defining one's location never 
changes during an update. If such a record must be reallocated, the new address of 
the contents of the record is stored in the header of the initial allocation, and an 
indication is made that the record is found indirectly. The reference count of keys 
kept with each stationary record permits deletions to take place in a manner that 
postpones the removal of an allocation until all references to it have been removed. 



Record Locks 

Record locks provide a basis for synchronizing concurrent access at the individual 
record level. The setting and clearing of record locks is explicitly controlled by the 
user via the record_status order. 

There are two types of records that may be locked. The more general facility requires 
that records be of the stationary type, created under the -stationary attach control 
argument. Each stationary record has a lock, modifier code, and a time of its last 
modification. It is a fundamental property of such a record that the storage occupied 
by its synchronization elements resides in a fixed location for the life of the record. 
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Thus, it is never necessary to lock the file in order to lock a stationary record if its 
descriptor is known. Use of the time last modified permits purely passive 
synchronization (i.e., without locking) to be done at the record level. This involves the 
use of a protocol such as the following: 

1. Obtain the record's time_last_modified with record_status, which may abort if 
the record lock remains set for longer than the allowed wait_time currently in 
effect. The record lock is always examined before returning the record's 
time_last_modif ied. 

2. Reference the record's contents via its pointer, obtained from the from the 
previous call to record_status. 

3. Use the block_ptr obtained from record_status to reexamine its time_last_modified. 
If unchanged, the passive reference is verified, and the operation is done. On 
the other hand, if the time_last_modified has changed, go back to step 1. 

In order to synchronize access at the record level without having to lock the file, it 
is necessary that record locks have a fixed location. Stationary records should 
therefore always be used, except when it is known that there will be no deletions or 
rewrites requiring reallocation. 

A different implementation of locks applies to nonstationary records. The modifier 
and time_last_modified are not supported, and the record lock is only supported if 
the user is careful to maintain allocations of sufficient size. 

When the capacity of an allocated record block exceeds its contents by at least four 
bytes, the last word of the block is treated as a record lock. A nonzero lock 
identifies the process that set it. The user can ensure that record allocations leave 
room for a lock by using the min_block_size order with a residue specification of at 
least four bytes. 

All orders that reference the length or contents of an existing record (e.g., seek_key, 
but not seek_head) also check the lock of the record (if one exists). If the record is 
not locked, the operation proceeds normally. Otherwise, the returned error code 
reflects the state of the lock, indicating that the contents of the record may be in an 
inconsistent state. In this case, if the order does not explicitly involve changing the 
file, it proceeds normally and the returned code is: error_table_$record_busy, if the 
record is locked by another live process; error_table_$lock_is_invalid, if the record's 
lock is set, but not by an existing process; or error_table_$locked_by_this_process, if 
the record is locked in the caller's process. 

Attempting a rewrite_record or delete_record order on a record locked by another 
process has no effect other than to return the code error_table_$record_busy (file is 
unchanged). If the lock is invalid, these orders return the code 
error_table_$invalid_lock_reset and zero the lock. If the lock was set by the caller, 
the code returned is error_table_$locked_by_this_process. In either of these latter 
cases, the operation is successful 
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If a record has been locked by a transaction, the above error codes are suppressed, 
except for the case of record_busy on an attempt to alter a record locked by a live 
process. If the record is not locked by another live process and the record's modifier 
can not be found in the transaction control file, or if the caller has not used the 
-transaction attach option, then the code error_table_$higher_inconsistency is returned. 

When a record that is locked by the user's process is rewritten, its lock remains set, 
as long as the minimum block size specification currently in effect leaves enough 
room for a recordjock: 



Interrupted Openings 

If a process opens a file and terminates without closing the file, the file may be left 
in an intermediate state that prohibits normal I/O operations on the file. The 
exception is opening for input only. In general, the bit counts of the file's segments 
will not be properly set, and the file contents will be in a complex intermediate state 
(e.g., a record, but not its key in the index, will be deleted). This situation is 
detected at a subsequent open or at the beginning of the next operation, if the file is 
already open with the -share control argument Unless the opening is for input only, 
the file is automatically adjusted; otherwise, the code error_table_$file_busy is 
returned. 

When an indexed file is adjusted, the interrupted operation (write_record, rewrite_record, 
delete_record, etc.), if any, is completed. For rewrite_record, however, the bytes of 
the record may be incorrect, unless stationary type records are used. (Everything else 
will be correct) In this case, an error message is printed on the terminal. The user 
can rewrite or delete the record as required. The completion of an interrupted write 
operation may also produce an incorrect record, in which case the defective record is 
automatically deleted from the file. 

Any type of file may be properly adjusted with the vfile_adjust command if an 
interrupted opening has occurred. 

SEQUENTIAL FILES 

The following paragraphs describe exceptions and provide information applicable to 
sequential files. For general information on the subjects mentioned, see the 
Programmer's Reference Manual. 



Position Operation 

The type 2 position operation is not supported for sequential files. 
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Write Operation 

The write operation is supported in files open for update. The effect is to append a 
record to the file or replace the next record, depending on the next record position. 

* 

Rewrite Operation 

For sequential files, the new record must be the same length as the replaced record. 
If not, the code returned is error_table_$long w record or error_table_$short_record. 

Delete Operation 

For sequential files, the record is logically deleted but the space it occupies is not 
recovered. 

* 

Logically Absent Records 

In a sequential file, the logical effect of a deletion is absolute in the sense that the 
result is the same as if the record had never been written in the first place. No 
subsequent operation can make the presence of such a record known to the user, 
although the storage that it occupies is not reused for the life of the file. The logical 
position of a deleted record is not reserved, but is assigned to the following 
nondeleted record, with the logical positions of subsequent records diminished 
accordingly. 



Interrupted Openings 

If a process opens a file and terminates without closing the file, the file may be left 
in an intermediate state that prohibits normal I/O operations on the file. The 
exception is opening for input only. In general, certain descriptors in the file and the 
bit count of the file's last segment will not be properly set This condition is detected 
at a subsequent open, and either the file is automatically adjusted or (if the opening 
is input only) the code error_table_$file_biisy is returned. 

Any type of file may be properly adjusted with the vfile_adjust command if an 
interrupted opening has occurred. 

UNSTRUCTURED FILES 

The following paragraphs describe exceptions and provide information applicable to 
unstructured files. For general information on the subjects - mentioned, see the 
Programmer's Reference Manual. 
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Position Operation 



In addition to the standard iox_ positioning, another type of positioning is available 
with files that are open for input or input_outpuL When the type argument of the 
iox_$position entry point is 2, this specifies direct positioning to the byte whose 
ordinal position (0, 1, 2,...) is given. The zero position is just beyond the file header, 
if a header is present 



Interrupted Openings 

If a process opens a file and terminates without closing the file, the file may be left 
in an intermediate state that prohibits normal I/O operations on the file. The 
exception is opening for input only. In general, the bit count of the file's last 
segment will not be properly set. This condition is not detected at subsequent 
openings, and part of the file's contents may be overwritten or ignored. 

Any type of file may be properly adjusted with the vfile_adjust command if an 
interrupted opening has occurred. 

CONTROL ORDER DESCRIPTIONS 

The remainder of this section describes the control orders, which are arranged 
alphabetically. Information concerning the usage of control orders from command level 
is located at the end of each description. The short names of the orders (where they 
exist) are provided in the format lines; use of either the long or the short name is 
acceptable in a command line. For general, rather than order specific, information, see 
"Control Operations from Command Level" earlier in this description. 



Name: add__key, ak 

The add_key order creates a new index entry with a given key and record descriptor. 

The I/O switch must be open for direct_output, direct_update, keyed_sequential_output, 
or keyed_sequential_update. Current and next record positions are unchanged. 

Associations may be formed between any number of keys and a single record via this 
order. Duplicate keys may be added if the file is attached with the -dup_ok control 
argument, or if the file already contains duplications; otherwise, the code 
error_table_$key_duplication is returned (see "Duplicate Keys" above.) 

When the -stationary control argument is used, the addition of a key to a stationary 
type record increments the record's reference count, in addition to inserting a new 
index entry (see "Multiply Keyed Records" above under "Indexed Files"). 

The current implementation restricts a user from adding more than 65,535 (2**16-1) 
keys to a single stationary record, returning the code error_table_$too_many_refs. 
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This order and the delete_key, reassign_key, and get_key orders do not reference the 
length or contents of a record. This permits one to avoid the use of actual records 
altogether in any given indexed file. 

For this order, the info_ptr argument must point to a structure (declared in the 
include file ak_info.incl.pll) of the following form: 

del 1 ak_info based (info_ptr), 

2 flags al igned, 

3 input_key bit(l) unal, 

3 input_desc bit(l) unal, 

3 mbz bi t (3^) unal , 

2 descrip fixed bin(35)» 

2 key_len fixed bin, 

2 key char (256 refer (ak_i nfo.key_len) ) ; 



STRUCTURE ELEMENTS 



input_key 

indicates whether the new key is given in the info structure. (Input) 

"0"b indicates that the current key for insertion is the new key. If this value is 

undefined, the code error_tableJSno_key is returned. 
"l"b indicates that the key to be added is the key_string contained in this info 

structure. 



input_desc 

indicates whether the new descriptor is given in the info structure. (Input) 

"0"b indicates that the current record defines the new descriptor. If the current 

record is undefined, the code error_table_$no_record is returned. 
"l"b indicates that the user-supplied descriptor in this info structure is the new 

descriptor. 



mbz 

must be set to zero by the user. (Input) 



descrip 

is used only if the variable input_descrip is set to 'T'b. (Input) The descriptor is 
stored into the index together with its associated key. Any 36-bit quantity may be 
supplied, although in general this number is a result of a previous record_status 
or get_key order. Descriptors are used by operations that reference the contents 
or length of a record, in order to obtain the record's address. 

keyjen 

is the length of the key_string. (Input) 

key 

is used only if ak_info.input_key is set to 'T'b. (Input) It defines the key to be 
added to the index with the appropriate record descriptor. 
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COMMAND LEVEL 
Syntax: 

io_call control switch_name ak {args} 

where: 
flags 

is a string of two bits corresponding to the switch settings for input_key and 
input_descrip. If one argument is given, it is interpreted as a key to be added to 
the current record, i.e., flags defaults to "10"b. 

key 

is a character string that must be given if flags. input_key is set. 
descrip 

is an octal descriptor that must be supplied if flags. input_descrip is set. 



Name: delete key, dk 

The delete_key order deletes a specified index entry. 

The I/O switch must be open for direct_update or keyed_sequential_update. The 
current and next file positions are left unchanged, with the following exception: if the 
deleted index entry is at the next record position, then the next record position is 
advanced to the following index entry, or becomes undefined in direct openings. 

When the -stationary control argument is used, the deletion of a key from a 
stationary type record decrements its reference count. The user cannot remove the last 
key in such a case (i.e., causing the reference count to vanish); the code 
error_table_$last_reference is returned. 

For this order, the info_ptr argument may be null, or it may point to a structure 
whose form is identical to the structure (declared in the include file ak_info.incl.pll) 
for the add_key order, in this way: 

del 1 dk info like ak info 
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where: 



input_key 

indicates whether the key is given in the info structure. (Input) 
"0"b indicates that the key associated with the current file position defines the 
key of the index entry that is to be deleted. If current position is 
undefined or outside the index (e.g., after deleting the current key of the 
current record), the code error_table_$no_key is returned. 
"l"b indicates that the user-supplied key_string defines the key of the entry to be 
deleted. If no such key is found, the code error_table_$no_key is 
returned. 

input_descrip 

indicates whether the descriptor is given in the info structure. (Input) 

"0"b indicates that the index entry to be deleted is associated with the current 

record. If the current record is undefined, the code error_table_$no_record 

is returned. 

"l"b indicates that the entry to be deleted is associated with the user-supplied 
descriptor. If no such entry exists, the code error_table_$no_record is 
returned. 

descriptor 

is used only if delete_key_info.input_descrip equals "l"b. (Input) The entry that is 
deleted is the first whose descriptor matches this value, among those entries with 
the specified key. 

key_length 

is the length of the key_string. (Input) 

key_string 

if delete_key_info.input_key equals "l"b, this argument defines the key for which 
the index entry with the specified record descriptor is to be deleted. (Input) 

mbz 

must be set to zero by the user. (Input) 

If the info_ptr argument is null, the index entry at the current file position is 
deleted, i.e., the effect is the same as that of setting both arguments, input_key and 
input_descrip, to "0"b. 

NOTES 

The interpretation of the descriptor argument as a record locator is not mandatory, 
since the add_key and reassign_key orders permit the user to set the descriptor 
portion of an index entry to an arbitrary 36-bit value. 

The descriptor itself may be thought of as a one-word record that is read by the 
get_key order. 
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COMMAND LEVEL 
Syntax: 

io_call control switch_name dk {args} 

where args are the same as for add_key above (flags, key, descrip). Optionally, if no 
arguments are given, the order is equivalent to a delete_key order with no info 
structure (null info_ptr). 



Name: error status, er 



The error_status order is accepted when the I/O switch is open and attached to an 
indexed or sequential file. The order returns information about the most recent 
attempt to position beyond either the beginning or the end of file in the current 
opening. 

For this order the info_ptr argument must point to a structure of the following form: 

del 1 error_info based (info_ptr), 

2 version fixed bin, 

2 type fixed bin, 

2 requested fixed bin(3^)» 

2 received fixed bin (3*0; 



STRUCTURE ELEMENTS 



version 

must be set to one by the user. (Input) 



type 

indicates the type of error that has occurred. (Output) 

0 no errors 

1 attempt to position beyond end or beginning of file, 
requested 

gives the value of the position skip argument that led to the most recent error. 
(Output) 

received 

gives the actual number of records successfully skipped before encountering end or 
beginning of file (negative if backwards skip). (Output) 
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COMMAND LEVEL 
Syntax: 

io_call control switch_name er 
where this prints the requested and received counts for the most recent skip error. 



Name: exclude, ex 

The exclude order causes subsequent vfile_ operations to behave as if a subset of 
records and their keys are absent from an indexed file. The exclude order excludes all 
of the keys associated with the records identified in the order. This process may 
remove more keys from the index than are identified explicitly in the order. 

The subset of interest may be specified in terms of ranges of keys, a list of record 
descriptors, or an identifying number for a previously formed subset. 

Various items of information that may be returned include a subset number, count of 
distinct descriptors, or an identifying number for a previously formed subset. 
However, status_only may not be requested via exclude. 

None of the file position designators (current and next record positions) are affected 
by this order. 

If no selection or exclusion is currently in effect (subset number=0), then a new 
subset will be formed defining the set of record descriptors to be excluded. The 
subset number in this case will be negative, indicating that a pure exclusion is in 
effect. 

If a pure exclusion is initially in effect, a subsequent exclude order has the effect of 
enlarging the current subset (i.e., the set of things to be excluded), and the. current 
subset number is unchanged. 

If a selection is in effect (subset number > 0), then the effect of a subsequent 
exclude order is to remove the specified descriptors from the current subset, again 
leaving the current subset number unchanged. 
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For this order, the info_ptr argument must point to one of the following structures 
(all declared in the include file select_info.incl.pll): 



del 1 common_s l_i nf o 
2 flags 

3 1 i st_type 

3 status_only 

3 output_descr i ptors 

3 del ete_old_subsets 

3 mbz 

3 version 
2 array_l imi t 
2 subset_no 
2 count 
2 desc_arrayp 



based (i nfo_ptr) , 
al i gned , 



xed bi n (3) unal , 
t(l) unal, 
t(l) unal, 
t(l) unal, 
t(ll) unal, 
xed bi n (17) unal , 
xed bin (19) , 
xed bin, 
xed b i n (3*0 , 



ptr ; 



where common_sl_info.desc_arrayp may point to the following structure: 

del desc_array (1 : common_sl_i nfo. count) fixed bin (35) 
based (si 1 nf o.desc_ar rayp) ; 



or: 



del 1 



hi_sl_info based (info_ptr), 

2 common like common_s l_i nf o, 

2 i nterva 1 (1 : s l_array_l i mi t refer (h 1 s 1 I nfo.array_l imi t) ) 

3 first_head, 

fixed bin, 
ptr unal , 



k length 
h kptr 
1 ast_head , 
h length 
4 kptr 



fixed bin, 
ptr unal ; 



or: 

del 1 da_sl_info 
2 common 



based (i nf o_ptr) , 
like common si info, 

i nfo,array_l imi t) ) 



2 desc_array (1 : sl_array_l imi t refer (da_sl 

f i xed bin (35) *» 
del s l_array_l imi t fixed bin; 

del s l_i nf o_vers i on_0 static opt i ons (constant) 

fixed bin ini t (0) ; 



i nterna 1 
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STRUCTURE ELEMENTS 
flags.list_type 

is a code indicating the manner in which this info structure specifies a subset: 
(Input) 

list_type=0 

causes the reuse of a subset formed earlier in this opening, whose subset 
number is given in sl_info.subset_no. 

list_type=l 

indicates that the subset is specified in terms of ranges of keys, or index 
intervals, using a structure like hi_sl_info. The code error_table_$no_record is 
returned if no index entries in the current subset are found in the specified 
set of intervals. 

list_type=2 

indicates that a list of descriptors with a structure like da_sl_info will be 
used to define the subset of interest. 

flags.status_only 

if set, status information will be returned for the current subset without making 
any subset changes. (Input) 

flags. output_descriptors 

if set, causes a sorted list of descriptors for the resulting subset to be output into 
the structure desc_array. (Input) 

flags.delete_old_subsets 

if set, and list_type = 1 or 2, causes all existing subsets to be deleted. The 
current subset number must be 0. (Input) 

version 

is the version number for this info structure, which should be set to 
sl_info_version_0. (Input) 

array_limit 

gives the number of array elements in this info structure. (Input) 
subset_no 

is an identifying number for the resulting subset, which permits its subsequent 
reuse in the same opening. A new subset is defined for each select order unless 
the user explicitly specifies reselection by giving the subset number as an input 
argument (list_type=0). The default subset is the identity case (i.e., the whole 
file), denoted by subset_no=0. A negative subset number indicates that the current 
subset is defined in terms of a set of records to be excluded. (Input /Output) 



3-241 



AG93-05 



vfile_ 



vfile_ 



count 

is the number of distinct record descriptors for the resulting current subset. 
(Output) 

desc_arrayp 

is used only if the flag, output_descriptors, is set (Input/Output) If null, the 
required desc_array structure will be allocated in system_free_area, and its address 
will be returned in desc_arrayp. Otherwise, desc_arrayp is assumed to point to an 
already allocated structure of sufficient size, in which the sorted list of 
descriptors (with duplications removed) is returned. 

desc_array 

is an optionally returned list of record descriptors in the current subset, sorted 
and with duplications removed. (Output) 

first_head. length 

is the number of bytes in the key string that defines the starting head for this 
range of keys. (Input) 

first_head.kptr 

gives the location of the character string that specifies the first head of this 
index interval. Every key in the interval must have a head that is greater than or 
equal its first_head. (Input) 

last_head. length 

is the number of bytes in the key string that defines the end of this index 
interval. (Input) If this number is negative, then one of the following applies: 

last_head. kptr = f irst_head. kptr 

indicates that this interval pertains only to keys that exactly match the given 
first_head. 

last_head.kptr A = f irst_head. kptr 

specifies that this is an "open" interval, whose largest key must have a head 
that is less than the given lastjiead. The length of the last_head is the 
absolute value of last_head. length in this case. 

Otherwise, if las t_head. length >=0, then a "closed" interval is specified, whose 
keys must have heads that are less than or equal to the given last_head. 

last._head.kptr 

gives the address of the last_head. (Input) If this is equal to first_head.kptr and 
last_head.length<0, the effect is the same as if both the first and last heads for 
this interval are the same and have been padded with blanks. Indicating an exact 
key match in this manner permits the user to avoid having to pad each key to 
256 characters, which might require considerably more storage and processing. 

da_sl_inf o.desc_array 

contains a list of record descriptors that define the subset of interest. (Input) The 
list may be unordered and may contain duplications. 
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COMMAND LEVEL 
Syntax: 

io__ca11 control switch_name ex {args} 

where: 
-brief, -bf 

suppresses the printing of the current subset number, descriptor count, and any 
error messages except the errors no_operation and bad_arg. 

-list, -Is 

prints the list of descriptors for the resulting subset. 

-delete_old_subsets, -dos 

deletes all existing subsets, before the new subset is created. This is incompatible 
with the -list control argument. The current subset number must be 0. 

(-head, -key) interval_specl ({-or, -or_key} interval_spec2 
({-or, -or_key} interval_spec3...)) 

specifies the subset in terms of ranges of keys where: 

-head 

indicates that the following interval starts with the first key whose head is 
greater than or equal to the specified first_key. This control argument is the 
def ault. 

-key 

indicates that the following interval is defined as those keys exactly matching 
the specified first_key . A last_key may not be given for this interval. 

interval_spec 

is of the form: 

first_key ({-thru, -to} last_key) 

where: 
first_key 

is a character string that defines the starting point for a range, or 
interval of keys. 

last_key 

is a character string giving the head that defines the end of an index 
interval. Its default value is that of the first_key. 

-thru 

separates the first and last key specifications for a closed index interval, 
i.e. keys with heads that are less than or equal to the last_key. 
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-to 

separates the first and last key specifications for an open index interval. 
Keys whose head is equal to or greater than the last_key are not 
included in this case. 

-or 

delimits the start of another interval specification that is of the default type; 
i.e., the following interval starts with the first key whose head is greater than 
or equal to the next first_key specification. 

-or_key, -ork 

delimits the start of an interval specification of the type that follows the 
-key control argument. 

{-or, -orjcey} interval_specl (interval_spec2...) 
is the same as above, except: 

-or 

if the first argument, it is taken as the default delimiter, and should be 
omitted between interval specifications following on this command line= 

-or_key, -ork 

if the first argument, it is taken as the default delimiter, and should be 
omitted between interval specifications following on this command line. 

{-desc} descriptor_list 

specifies the subset in terms of a list of record descriptors where: 

-desc, -ds 

indicates that the subset specification for this order is in terms of a list 
of descriptors that follows. 

descriptor_list 

is a list of octal record descriptors. 

{-reset} subset_number 

specifies the subset in terms of an identifying number for a previously 
formed subset where: 

-reset, -rs 

indicates that a previously formed subset is to be reused. If no 
subset_number follows, subset 0 is assumed. 

subset_number 

is the identifying subset number for the subset to be reused. 
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Name: file status, fs 

The file_status order is accepted when the I/O switch is attached (open or closed). 
Various items of information about the file are returned. The info_ptr argument must 
point to a structure identical to one of those required for the vfile_status_ subroutine. 

COMMAND LEVEL 

Syntax: 

io_call control switch_name fs 
where the output is the same as that of the vfile_status command. 



Name: get key, gk 

The get_key order returns both the key and the record descriptor for the specified 
index entry in a file opened for keyed_sequential_input or keyed_sequential_update. 

An index entry may. be specified in terms of the current or next positions, by 
association with a given descriptor, or by bearing the specified relation to a given key. 
If the requested index entry does not exist, one of the codes, error_tabie_$no_record 
or error_table_$no_key is returned, whichever is appropriate. Optionally, the user can 
indicate that the final position is to be left unchanged. Otherwise the current and 
next record positions are set to the specified index entry. 

For this order, the info_ptr argument must point to a structure (declared in the 
include file ak_info.incl.pll) of the following form: 

del 1 gk_info based (info_ptr), 

2 f 1 ags al i gned, 

3 input_key bit(l) unal, 

3 input_desc bit ( 1 ) unal, 

3 desc_code fixed bin (2) unal, 
3 pos i t i on__spec i f i cat i on unal, 

h current bit(l) unal, 

h rel_type fixed bin (2) unal, 

h head_size bit (9) unal, 

3 reset_pos bit(l) unal, 

3 mbz bi t (8) unal , 

3 version fixed bin(8) unal, 

2 descrip fixed bin(35)» 

2 key_len fixed bin(17), 

2 key char (256 ref er (gk_i nf o.key_l en) ) ; 
del gk_info_version_0 fixed bin static init(O); 
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STRUCTURE ELEMENTS 
input_key 

if set to "l"b indicates that the key in this info structure is an input argument, 
which must bear the specified relationship to a key in the index. Otherwise the 
key of interest is located through either the next or the current position, 
according to the setting of flags. current. (Input) 

input_desc 

if set to 'T'b indicates that the desired index entry must have a descriptor that is 
equal to that given in this structure as an input argument. Otherwise the 
descriptor may either have any value or must be that of the current record, as 
specified by the setting of flags. desc_code. (Input) 

desc_code 

is used only if flags. input_desc="0"b to specify the desired descriptor portion of 
an index entry. If desc_code=0, then any descriptor is satisfactory. If desc_code=l, 
then the index entry of interest must be associated with the current record. No 
other desc_code settings are defined in this implementation. (Input) 

current 

applies only if flags. input_key="0"b. If set to "l"b, this indicates that the current 
index entry is the one of interest. This control argument conflicts with the setting 
of flags.input_desc to 'T'b. Otherwise, if flags.current="0"b, the next record 
position is used as a starting point to find the desired index entry by scanning 
for the next occurrence of the desired descriptor, until end of file is encountered, 
or until the next key ceases to satisfy an immediately preceding successful 
seek_head order. Index entries are always scanned in ascending order, except 
immediately after a successful backwards position skip operation, when scanning is 
done in reverse. (Input) 

rel_type 

applies only if flags.input_key="l"b. This indicates the desired relationship that 
the head of a key in the index must have with the key_string given in this info 
structure. Allowed values and their meanings are the same as those for the 
seek_head order. (Input) 

head_size 

applies only if flags.input_key="l"b, specifying the number of characters in the 
key_string contained in the desired head. (Input) 

reset_pos 

if set to "l"b, the state of the file position designators will be left unchanged by 
this order. Otherwise the current and next record positions will be left at the 
specified index entry. (Input) 

version 

is the version of this info structure, which should be set to gk_info_version_0. 
(Input) 
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descrip 

is the record locator portion of the specified index entry. If flags.input_desc="l"b, 
this is an input argument. Descriptors may also be input to the control orders 
add_key, delete_key, reassign_key, and record_status (see "Notes" below). 
(Input/Output) 

key_len 

is the length of the key for the specified index entry. (Input/ Output) 

key 

if flags.input_key="l"b, this is an input argument that contains the desired key 
head. The value that is returned is the key of the specified index entry. 
(Input/ Output) 

mbz 

must be set to zero by the user. (Input) 
NOTES 

If flag.input_key is equal to "l"b, both head_size and key_len should be initialized to 
zero or assigned an appropriate value. 

COMMAND LEVEL 

Syntax: 

i o_cal 1 control swi tch_name gk {args} 

where: 
-brief, -bf 

suppresses printing of the key, its descriptor, and any error messages except for 
the errors no_operation and bad_arg. 

-head key_string ({-rel_type} N) 

indicates that the following argument is to be taken as the key giving the head 
that must bear the specified relationship to the key of the desired index entry. 
This argument need not be given if the key_string cannot be confused with one 
of the optional arguments to this order. 

key_string 

if specified, this is the string that defines the key portion of the index entry 
of interest. If no key_string is specified, and -cur_pos is not given, then the 
next record position is used. 

-rel_type, -rel 

applies only when a key_string is specified. This argument must be followed 
by a number that defines a valid relationship between the given key_string 
and the head of a key in the index. If not specified, -rel 0 is assumed, 
when applicable. 
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N 

is the first N characters of the key. The allowed values are: 

0 head = search_key 

1 head >= search_key 

2 head > search_key 

See the seek_head order for more information. 

-cur_pos 

indicates that the index entry of interest is at the current record position. This 
control argument conflicts with a key_string specification. 

-current, -cur 

specifies that the desired index entry belongs to the current record. If neither 
this nor the -desc control argument is given, the first index entry encountered 
that satisfies the key_specification is specified by default 

-desc DESCRIPTOR, -ds DESCRIPTOR 

specifies that the desired index entry has a given descriptor, which must be the 
next argument. DESCRIPTOR is an octal record descriptor, like those returned by 
this order. 

-reset, -rs 

causes the final position to be left unchanged. If not specified, the final positions 
correspond to the specified index entry. 

-substr offset Llength} 

specifies a substring of the key to be returned where OFFSET is the starting 
character position of the key to be returned, and LENGTH is the length of the 
part of the key to be returned. If LENGTH is omitted, the entire tail of the 
key is returned. 

If this order is issued through an io_call active function, only the key is returned. 
Use of the -brief control argument suppresses any error messages except for the 
no_operation and bad_arg errors. 

If no arguments are supplied, the next index entry is located. 



Name: max rec len, mx 

The max_rec_len order is accepted when the I/O switch is open and attached to a 
blocked file. The order returns the maximum record length (bytes) of the file. A new 
maximum length can be set by specifying a nonzero value for the second argument. 
In this case the file must empty and open for modification, or the code 
error_table_$no_operation is returned. 
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For this order the info_ptr argument must point to a structure of the following form: 



del 1 info based (info_ptr), 

2 old_max = recl fixed bi n (21) 9 /*output*/ 
2 new_max_recl fixed bin (21); /* input*/ 



COMMAND LEVEL 
Syntax: 

io_call control switch_name mx {arg} 

where: 
arg 

is an integer specifying a new maximum record length. 
This prints the old maximum record length. 

Name: min block size, mb 

The min_block_size order determines the minimum size for blocks of record space 
that are subsequently allocated by write_record or rewrite_record operations (documented 
in the iox_ subroutine). The specification remains in effect for the duration of the 
current opening or until another call to this order is issued. The I/O switch must be 
attached to an indexed file open for output or update. 

For this order, the info_ptr argument must point to a structure of the following 
form: 

del 1 mi n_b 1 ksz_i nf o based (info_ptr), 
2 min_residue fixed bin(21), 
2 min_capacity fixed bin (21); 

STRUCTURE ELEMENTS 

min_residue 

specifies the minimum unused capacity of a record block (bytes); i.e., the 
difference between the record's length and the maximum length it can attain 
without requiring reallocation. (Input) 

min_capacity 

specifies the minimum total record capacity (bytes); i.e., the maximum length that 
the record can attain without requiring reallocation. (Input) 

When the I/O switch is initially opened, both these parameters are set to zero. 
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The current implementation imposes the following constraints on allocated record 
blocks: 

1. The minimum allocation is eight full words, including two header words for the 

block length and record length. Six more words of overhead are required for 
stationary type records. The minimum nonnull record capacity is, therefore, 24 
bytes, or 0 bytes in the case of stationary records. 

2. The size of an allocated block is always an even number of full words, i.e., a 

multiple of eight bytes. 

The formula below gives the allocation size, block_words, used for a rewrite_record, 
write_record, or record_status order with a given buffer length, buff_len: 

block_words - 0 (no allocation if and only if buff Jen and min_residue and 
min_capacity all are equal to 0. A nonnull allocation is always left 
when rewriting a stationary record or upon record creation under the 
-stationary attach option.) 

otherwise: 

block_words = max (8,(max(buff_len + min_residue, min_capacity) + 7) / 8) 
COMMAND LEVEL 
Syntax: 

io_call control switch_name mb {args} 

where: 
min_res 

is an integer. The default is 0. 

min_cap 

is an integer. The default is 0. 
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Name: read position, rp 

The read_position order is accepted when the I/O switch is open and attached to a 
nonindexed file. The order returns the ordinal position (0, 1, 2, ...) of the next 
record (byte for unstructured files), and that of the end of file, relative to the file 
base. The file base is just beyond the header, if a header is present 

For this order, the info_ptr argument must point to a structure of the following 
form: 

del 1 info based (info_ptr), 

2 next position fixed bin (3*0 » /^output*/ 
2 1 ast_pos i t i on fixed bin (3*0; /^output*/ 

COMMAND LEVEL 

Syntax: 

io_call control switch_name rp 
where this prints the next record (or byte) and end of file positions. 



Name: reassign key, rk 

The reassign_key order causes the descriptor portion of a specified index entry to be 
replaced with a given value. 

The I/O switch must be open for direct_update or keyed_sequential_update. The file 
position designators are not changed. 

When the -stationary control argument is used, the reference counts of any stationary 
records involved are adjusted accordingly, as described for add_key and delete_key. 
The code, error_table_$last_reference is returned if the user is prevented from 
removing a record's last key. 

The current implementation restricts a user from adding more than 65,535 (2**16-1) 
keys to a single stationary record, and returns the code error_table_$too_many_refs. 
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For this order, the info_ptr argument must point to a structure (declared in the 

include file ak_info.incl.pll) of the following form: 

del 1 rk_info based (info_ptr), 

2 flags al igned, 

3 input_key bit(l) unal, 

3 i nput_ol d_desc bit(l) unal, 

3 i nput_new_desc bit(l) unal, 

3 mbz b i t (33) unal ,. 

2 old_descrip fixed bin(35)» 

2 new_descrip fixed bin(35)» 

2 key_len fixed bin, 

2 key char (256 ref er (rk_i nf o. key_l en) ) ; 



STRUCTURE ELEMENTS 



input_key 

indicates whether the key is given in the info structure. (Input) 

"0"b indicates that the index entry to be reassigned has as its key the current key 

for insertion. If undefined, the code error_table_$no_key is returned. 
"l"b indicates that the key_string argument defines the key portion of the index 

entry to be reassigned. If the key_string is not found in the index, the 

code error_table_$no_key is returned. 

input_old_desc 

indicates whether the old descriptor is given in the info structure. (Input) 

"0"b indicates that the entry to be changed is associated with the current record. 

If the current record is undefined, the code error_table_$no_record is 

returned. 

"l"b indicates that the oid_descrip argument defines the descriptor portion of the 
index entry to be changed. 

input_new_desc 

indicates whether the new descriptor is given in the info structure. (Input) 

"0"b indicates that the specified index entry is to be reassigned to the current 

record. If the current record is undefined, the code error_table_$no_record 

is returned. 

"l"b indicates that the argument new_descrip is to supply the new value for the 
descriptor portion of the specified index entry. 

old_descrip 

is used only if rk_info.input_old_desc equals "l"b. (Input) The entry that is 
reassigned is the first whose descriptor matches this value, among those index 
entries with the specified key. 

new_descrip 

is used onlv if rk_info.input_new_desc equals "l"b. This value replaces the old 
descriptor of the specified index entry. (Input) 
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key_len 

is the length of the key_string. (Input) 

key 

if rk_info.input_key equals "l"b, this argument defines the key for which the 
index entry with the specified descriptor is to be reassigned. (Input) 

COMMAND LEVEL 

Syntax: 

io_call control switch_name rk flags {args} 

where: 
flags 

is a string of three bits corresponding to the switch settings input_key, 
input_old_desc, input_new_desc. 

args 

can be chosen from the following: 

key 

is a character string that must be given if flags. input_key is set. 
old_descrip 

is an octal number required if flags. input_old_desc is set. 
new_descrip 

is an octal number required if flags. input_new_desc is set. 



Name: record status, rs 

The record_status order returns information about a specified record in an indexed, 
sequential, or blocked file, and optionally permits the user to manipulate the lock of 
the record or to allocate an empty record or both (indexed files only). 

An argument is provided that permits the user to entirely avoid using the index in 
accessing and creating records (see "Notes" below). 

In blocked and sequential files, the current and next record positions may optionally 
be set to a given record number. 

The I/O switch must be open and attached to a structured file. The next record 
position is not altered or used by this order, unless the locate_pos_sw flag is set 
(unindexed files only). The current record position is always set to the record 
referenced. 
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If the file is sequential or blocked, the only nonzero flag setting permitted is 
locate_pos_sw. 

The I/O switch must be open for output ot update in order to lock, unlock, or 
create a record. 

For this order, the info_ptr argument must point to a structure (declared in the 
include file record_status.incl.pll) of the following form: 



rs_i nf o 


based (info_ptr) 


2 


version 


fixed bin, 


2 


f 1 ags 


al i gned, 




3 lock_sw 


bi t (1) unal , 




3 unlock_sw 


bi t (1) unal , 




3 create_sw 


bi t (1) unal , 




3 locate_sw 


bi t (1) unal , 




3 i nc_ref_count 


bi t (1) unal , 




3 dec_ref_count 


bi t (1) unal , 




3 1 ocate_pos_sw 


bi t (1) unal , 




3 mbzl 


bit (2y) unal, 


2 


record_l ength 


fixed bin (21) , 


2 


max_rec_l en 


fixed bin (21) , 


2 


record_ptr 


ptr, 


2 


descr i ptor 


fixed bin (35) , 


2 


ref_count 


fixed bin (17) , 


2 


t ime_l ast_mod i f i ed 


fixed bin(7D , 


2 


mod i f i er 


f i xed bin (3^) , 


2 


bl ock_ptr 


ptr unal , 


2 


last image modifier 


fixed bin (35) , 


L 


ill—*—. L. \ 1 / 


fixed bin; 



del rs_i nf o_vers ion_2 static internal fixed bin init(2); 

STRUCTURE ELEMENTS 

version 

is provided for compatibility with possible future versions of this info structure. 
(Input) The user should set this argument to rs_info_version_2. 

lock_sw 

indicates whether an attempt is made to lock the specified record within the wait 
time limit given at attachment or subsequently set via the set_wait_time order. 
(Input) 
"l"b yes 
"0"b no 
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Possible error codes are: 

error_table_$invalid_lock_reset 
error_table_$locked_by_this_process 
error_table_$record_busy 
error_table_$no_room_f or_lock 
error_table_$higher_inconsistency 

The code no_room_for_lock is returned if the allocated record block is too small 
to contain a lock. (See "Records Locks" above under "INDEXED FILES".) The 
code higher_inconsistency is returned if the lock was set by a transaction which 
cannot be adjusted, either because it is another transaction in the caller's process, 
or because the lock was set by a dead process and no tcf entry can be found for 
the record modifier. 

If the first modification of a record in a transaction is to lock (and not unlock) 
via record_status, then vfile_ automatically initializes an afterimage for the record 
with a copy of its before image. The record_ptr returned in this case points to 
the afterimage, so that based manipulations of the record via its pointer do not 
affect the before image: this guarantees that modifications made in this manner 
can be rolled back. Afterimage initialization is suppressed by setting rs_info.unlock_sw. 

unlock_sw 

indicates whether an attempt is made to unlock the record. (Input) 
"l"b yes 
"0"b no 

Possible error codes are: 

error_table_$lock_not_locked 
error_table_$locked_by_other_process 
error_table_$no_room_f or_lock 

If both lock_sw and unlock_sw are set to "l"b, the locking takes place first and 
determines the resultant error code. (This permits one to clear an invalid lock in 
a single operation.) 

When the -transaction attach option applies, records can not be unlocked 
explicitly, since they must be left locked until the transaction completes; unlocking 
is then done automatically. The only permissible use of setting rs_info.unlock_sw 
under -trans is in the case where rs_info.lock_sw is also set, in which case, the 
effect is to suppress setting the record's afterimage and to return a pointer to the 
before image allocation, leaving the record locked. This usage permits explicit 
synchronization for avoiding interference and deadlocks without incurring the 
added expense of preparing an afterimage when one has no immediate intention to 
rewrite. Based modifications of the record contents should not be made via the 
record_ptr returned by record_status in this case, but passive based references are 
allowed. The only valid way to perform based alterations of a record in a 
transaction is by obtaining a pointer to its afterimage. 
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create_sw 

indicates whether a new record is allocated using the record_len and max_rec_len 
arguments as input parameters. (Input) 
'T'b yes 
"0"b no 

The contents of the record are set to zero, and its lock is set in the same 
operation if lock_sw equals 'T'b. Depending upon the setting of locate_sw, the 
new record may be entered into the index. If locate_sw equals "0"b, the current 
key for insertion is added to the index as a key for the new record. Otherwise, 
no index entry is created and the key for insertion becomes undefined. 

locate_sw 

indicates how the record of interest is located. (Input) 

"0"b if create_sw also equals "0"b, this indicates that the current record position 
defines the record of interest. Otherwise, the current key for insertion is 
used. If the relevant position designator is undefined, the code 
error_table_$no_record or error_table_$no_key is returned, whichever is 
appropriate. 

'T'b if create_sw equals "0"b, this indicates that the descriptor argument is an 
input parameter defining the location of the record of interest. When such 
references are permitted in a shared file, users must observe certain 
protocols to ensure proper synchronization of access at the record level. 
Record locks are provided for this purpose. If create_sw equals "l"b, this 
causes the new record to be created without a key. 

inc_ref_count 

if set to 'T'b, the record must be of the stationary type, or the code 
error_table_$no_room_for_lock is returned. (Input) The effect of setting this flag 
is to increment the reference count of the record. 

The current implementation prevents a user from causing a reference count to 
exceed 65,535 (2**16-1), returning the code error_table_$too_many_refs. 

dec_ref_count 

if set to "l"b and the record is of the stationary type, this causes its reference 
count to be decremented. (Input) Users are not normally expected to manipulate 
the reference count of a record explicitly in this manner, unless list structures are 
maintained having direct references to records in terms of their descriptors within 
other records (see "Multiply Keyed Records" below). 

The code error_table_$last__reference is returned when the user is prevented from 
removing the last reference to a nondeleted record. 

locate_pos_sw 

if set to "l"b, the current and next record positions are first set to the record 
whose ordinal position is given in rs_info.record_length. (Input) The file must be 
either blocked or sequential. If the file is sequential, then the descriptor of the 
record must also be supplied as an input argument. 
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gives the record's length in bytes. {Input/ Output) If create_sw equals "l"b, this 
argument is input. 



max_rec_len 

if create_sw equals "l"b this argument is input and, if nonzero, overrides any 
minimum block size specification that may currently be in effect (see min_block_size 
order below). (Input/ Output) The returned value gives the maximum length that 
the record can attain (bytes) without requiring reallocation. When this argument is 
used . as an input parameter, the resultant maximum record length is the smallest 
number greater than or equal to max_rec_len that corresponds to an implemented 
(nonzero) block size. 

record_ptr 

is a pointer to the first byte of the allocated record, or is set to null if no 
allocated record exists. (Output) 

descriptor 

is a process-independent locator for the specified record. (Input/Output) This 
value is used as an input argument when locate_sw equals "l"b and create_sw 
equals "0"b. The actual structure of each descriptor (for indexed or blocked files) 
is as follows: 

del 1 descr i p_struct based (addr (descr i ptor) ) aligned, 
2 comp_num fixed bin (17) unal, 

2 word_offset b i t (1 8) unal; 

where: 
comp_num 

is the multisegment file component number of the segment containing the 
record. 

word_offset 

is the word offset of the block of storage containing the allocated record, 
relative to the base of its file component. 

A zero descriptor designates an unallocated (zero-length) record. 

Descriptors may also be arguments to the add_key, delete„key, reassign_key, and 
get_key orders. Note that at any given time within a single file each record is 
uniquely located by its descriptor, which remains valid only for the life of a 
single allocation. 
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ref_count 

is returned only if the record is of the stationary type, in which case this is the 
reference count of the record. (Output) When the -stationary control argument is 
used, vfile_ automatically maintains the reference counts of stationary records to 
reflect the number of keys on each record (see "Multiply Keyed Records" above). 

time_last_modif ied 

applies only for stationary records. (Output) Contains a standard system clock 
time for the most recent modification made to the current record. 



modifier 

if nonzero, this is the identifying number of a transaction on whose behalf the 
record was locked. (Input/ Output) When rs_info.lock_sw is set, the user should 
set this value to 0 before calling record_status. 

block_ptr 

points to the start of the allocated block for the record. (Output) The 

time_last_modified of a stationary record may be directly examined by using the 
following structure: 

del 1 stat_block aligned based (block_ptr) , 

2 double words (2) fixed b i n (7 1 ) i 

2 half_word fixed (17) unal , 

2 t ime_l astjnod i f i ed fixed bin (53) unal; 

Obtaining the time_last_modified via block_ptr avoids the expense of another call 
to record_status. 

last_image_modif ier 

is the transaction number for the most recent modification of this record. 
(Output) If zero, then the most recent modification was not made under the 
-transaction option. 



mbzl, mbz2 

must be set to zero by the user. (Input) 



Notes 



If locate_sw is set to "l"b, the resultant current record position moves "outside" of 
the index in the sense that there is if so, a subsequent rewrite_record or delete_record 
order behaves differently from the usual case. The difference is that no corresponding 
index entry is changed or deleted to reflect the change to the record. 

Extreme caution must be exercised when using the orders that take a descriptor as an 
input argument, especially in a shared environment The user is responsible for 
ensuring that previously obtained descriptors and pointers are still valid when they are 
used. Also, it is important to maintain the index in a consistent state, i.e., each index 
entry should designate a valid record if a record reference may be attempted. 
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Syntax: 

io_call control switch_name rs {args} 

where: 



-brief, -bf 

suppresses the printing of status information. If omitted, record_length, max_rec_len, 
record_ptr, and record descriptor (in octal) are printed; in addition, time_last_modified, 
reference_count, and modifier are printed for stationary type records. 

flags, -pos 

is a string of seven bits, corresponding to the switch settings for lock_sw, 
unlock_sw, create_sw, locate_sw, inc_ref_count, dec_ref_count, and locate_pos_sw. 
This argument defaults to "0000000"b if not given. The setting of locate_pos_sw 
may also be expressed by the use of the -pos control argument as an abbreviation 
for the corresponding specification of flags. 

reel 

is an integer that must be given when flags. create_sw is set. This determines the 
new record length. 

maxl 

is an optionally supplied integer that may be given with reel to specify a 
maximum record length. This defaults to reel if not given. 

descrip 

is an octal record descriptor required when flags. locate_sw is set and flags.create_sw 
is not set. 

pos_spec 

is a number or pair of numbers specifying the record's ordinal position (followed 
by the record's descriptor if the file is sequential). This specification is required 
and applies only when flags.locate_pos_sw is set. 



Name: seek head, sh 



The seek_head order is accepted when the I/O switch is open for keyed_sequential_input 
or keyed_sequential_update. For this order the info_ptr argument must point to a 
structure of the following form: 



del 1 info 

2 relation_type 
2 n 

2 search_key 



based (i nfo_ptr) , 
fixed bin, 
fixed bin, 

char (256 refer (info.n)); 
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The order locates the first record with a key whose head has the specified relation 
with the given search_key. The next record position and the current record position 
are set to the record. If no such record exists, the code error_table_$no_record is 
returned. 

The head of a record's key is the first n characters of the key, the key being 
extended by blanks if it has fewer than n characters. The allowed values for 
info.relation_type are: 

0 head = search_key 

1 head >= search_key 

2 head > search_key 

COMMAND LEVEL 
Syntax: 

io_call control switch_name sh {args} search_key 

where: 
-brief, -bf 

suppresses any error message except the no_operation and bad_arg errors. 
rel_type 

is a single digit, 0, 1, or 2. If omitted, the last argument is interpreted as a 
search_key, with a default rel_type of 0. 

search_key 

is any character string. 



Name: select, si 

The select order causes subsequent vfile_ operations to behave as if a subset of all the 
records and their keys were present in an indexed file. The select order selects all of 
the keys associated with the records identified in the order. This process may select 
more keys from the index than are identified explicitly in the order. 

Use (and include file) is the same as that described for the exclude order, except that 
status_only may be requested via select. 

The subset of interest may be specified in terms of ranges of keys, a list of record 
descriptors, or an identifying number for a previously formed subset. 

Various items of information that may be returned include a subset number, count of 
distinct descriptors, and a sorted list of descriptors. 

None of the file position designators (current and next record positions) are affected 
by this order. 
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New records may not be created while a selection is in effect. If attempted, the code 
error_table_$no_record is returned. 

COMMAND LEVEL 

Syntax: 

io_ca11 control swi tch_name si {args} 
where args are the same as those described for the exclude order. 

If no control arguments are given, the only effect is to print the status information 
for the current subset. 



Name: set file lock, sf 

The set_file_lock order is accepted when the I/O switch is open for output or update 
and attached to an indexed file with the -share control argument. For this order, the 
info_ptr argument must point to a variable of the following form: 

del set_l ock_f 1 ag bit (2) aligned based (info_ptr); 

This order causes the file to be locked (if possible within the wait_time limit) or 
unlocked, depending on whether the user has set the first bit of info_ptr->set_lock_flag 
to "l"b or "0"b, respectively. 

The possible error codes are: 

error_table_$locked_by_this_process 
error_table_$lock_not_locked 
error_table_$f ile_busy 

The second bit of set_lock_flag indicates the class of operations that are to be 
excluded by locking the file. If this bit is "0"b, only operations that alter the file are 
excluded (passive operations do not detect this state). Otherwise, all index referencing 
operations are excluded. In any case, the exclusion only applies to operations outside 
the current opening. 

COMMAND LEVEL 

Syntax: 

io_call control switch_name sf set_lock_f 1 ag 

where: 

set_lock_flag 

is a string of two bits. 
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Name: set„wait = time, sw 

The set_wait_time order is accepted when the I/O switch is open and attached to 

an indexed file with the -share control argument. For this order the info_ptr 
argument must point to one of the following structures: 

del new_wa i t_t i me float based (info_ptr); 
or: 

del 1 wt_info based (info_ptr), 

2 version float, /* Input'*/ 

2 col lection_delay_time float; /"Input*/ 

This order specifies a limit on the time that the user's process waits to perform 
an order when the file is locked by another process. The interpretation of 
new_wait_time is the same as that described earlier for the argument N used with 
the -share control argument. 

If wt_iiifo. version equals -2 (-2.0e0), the second argument is taken as a new 
collection_delay_time, in seconds. This specifies the amount of time that must 
elapse after deleting a stationary record before its storage can be completely 
recovered. Initially, in any opening, a default value of 0 applies. 

COMMAND LEVEL 

Syntax: 

io_call control switch_name sw {arg} new_wa i t_t i me 

where arg can be -collection_delay_time (-cdtm), and new_wait_time is a floating 
point number. If -cdtm is specified, new_wait_time is taken as the new collection 
delay time. 



Name: truncate, tc 

The truncate order is accepted when the I/O switch is attached to an unindexed file 
open for input_output or update. The order truncates the file at the next record (byte 
for unstructured files). If the next position is undefined, the code error_table_$no_record 
is returned. 

COMMAND LEVEL 

Syntax: 

io call control switch name tc 
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Name: window io 

The window_io_ I/O module supports I/O to a window. In addition to the usual 
iox_ entries, the module provides terminal independent access to special video terminal 
features, such as a moveable cursor, selective erasure, and scrolling of regions. The 
module provides a real-time input line editor and performs output conversion and 
"MORE" processing. 

Entry points in this module are not called directly by users; rather, this module is 
accessed through the I/O system interfaces iox_ and window_. 

ATTACH DESCRIPTION 



window_io_ switch {-contro ]_args} 



ARGUMENTS 
switch 

is the name of an I/O switch attached to a terminal via the tc_io_ I/O module. 
The window created by this attach operation will be mapped onto the screen of 
that terminal. Use window_$create to attach and open, and use window_$destroy 
to detach and close windows on the login terminal. 



CONTROL ARGUMENTS 
-firstjine LINE_NO 

LINE_NO is the line number on the screen where the window is to begin. If 
omitted, the window starts on the topmost line of the screen (line 1). 

-height N.LINES, -njines N_LINES 

N_LINES is the number of lines in the window. The default is to use all lines 
to the end of the screen. 

-first_column COL_NO 

COL_NO is the column number on the screen where the window is to begin. If 
omitted, the window starts on the leftmost column of the screen (column 1). 

-width N_COLS, -n_columns N_COLS 

N_COLS is the number of the columns in the window. The default is all columns 
to the end of the screen. 

NOTES 

The attach description control arguments must specify a region which lies within the 
terminal screen. If not, the attachment is not made, and the error code 
video_et_$out_of_terminal_bounds is returned. 
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When the window is attached, it is cleared and the cursor is left at home. 
OPEN OPERATION 

The following opening mode is supported: stream_input_output. 
PUR CHARS OPERATION 

This operation is used to output a character string to the window. If rawo mode (see 
below) is disabled, the characters are processed according to the output conversions 
defined for the terminal. If necessary, the string is continued on subsequent lines of 
the window. If output passes the last line of the window, the placement of additional 
lines is controlled by the setting of the more_mode mode (see below). If an output 
line must be erased from the window to make room for this new output, and there 
has been no intervening input in this window, and more_mode (see below) is enabled, 
the user is queried for the disposition of this new output. (See MORE processing in 
Section 4.) 

In rawo mode, the characters are written directly to the terminal, without any of the 
above processing. 

GET CHARS OPERATION 

This operation returns exactly one character, unechoed, Tegardless of the size of the 
caller's buffer. The line editor is not invoked by this call. 

GET LINE OPERATION 

The get_line operation invokes the real-time input line editor, and returns a complete 
line typed by the user. A description of the typing conventions is given in Section 4. 
The put_chars and get_line operations retrieve and reset any statuses that they 
encounter, so that applications that make these calls need not be changed to check for 
video_et_$window_status_pending. 

CONTROL OPERATION 

The control operations below are supported. Note that many of the control operations 
can be issued at command level via io_call commands; these include any control orders 
that do not require an info structure, and those described below. The following 
relations must hold when changing windows (set_window_info). These relations are 
always true when obtaining information about a window (get_window_info): 

0 < column + width <= screen width 
0 < line + height <= scrren height 
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get_window_info 

returns information about the position and extent of the window. The info 
points to the following structure (declared in window_control_info.incl.pll): 



ptr 



del 1 wi ndow_pos i t i on_i nf o 
2 version 
2 or ig i n, 

3 column 

3 1 i ne 
2 extent, 

3 width 

3 height 



based (wi ndow_pos i t i on_i nf o_ptr) , 
fixed bin, 

fixed bin, 
fixed bin, 

f i xed bin, 
fixed bin; 



STRUCTURE ELEMENTS 



version 

is the version number of this structure. 
window_position_inf o_version_2. 



(Input) It must be 



column 

is the column of the upper left-hand corner of the window. (Output) If the 
column of the upper left-hand corner is zero, then the first column will be 
used, to allow old programs written when this was a mbz field to run 
without modification. 



line 



is the line of the upper left-hand corner of the window. (Output) 



width 

is the width of the window (columns). (Output) 
height 

is the height of the window (lines). (Output) 
set_window_info 

causes the window to be relocated or to change size (or both). The info ptr 
points to the same structure used in the "get_window_info" control order. The 
values have the same meaning, but are the new values for the window when 
setting (Input), and are returned by get_window_info (Output). 
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get_window_status, set_window_status 

window status is used to inform the application that some asynchronous event has 
disturbed the contents of the window. When window status is set for a window, 
all calls to window_ will return video_et_$window_status_pending until the status 
is reset. To reset the status, make a get_window_status control order on the 
switch. The info pointer should point to the following structure (declared in 
window_control_inf o.incl.pll): 



del 1 wi ndow_status_i nf o aligned based (wi ndow_status_i nf o_ptr) , 
2 version fixed bin, 

2 status_str i ng bit (36) aligned; 



STRUCTURE ELEMENTS 



version 

is the version of this structure. (Input) It must be window_status_version_l. 
status_string 

is the window status information. (Input) To interpret the actual status_string, 
use the include file window_status.incl.pll: 

del 1 wi ndow_status_i nf o aligned based (wi ndow_status_i nf o_ptr) , 

2 screen_i nva 1 i d bit (1) unaligned, 

2 async_change bit (1) unaligned, 

2 ttp_change bit (1) unaligned, 

2 reconnect ion bit (1) unaligned, 

2 pad bit (32) unaligned; 



STRUCTURE ELEMENTS 



screen_invalid 

indicates that the contents of the window have become undefined. (Input for 
set, Output for get) This will happen, for example, in the event of a 
disconnection /reconnection of the terminal. 

async_change 

indicates that a timer or event call procedure has made a modification to the 
window. (Input for set, Output for get) 

ttp_change 

indicates that the terminal type has changed. (Input for set, Output for get) 
This re-initializes all the terminal specific video system information such as 
the video sequences, length and width of the screen, and capabilities. 
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reconnection 

determines the new terminal type (which may or may not be the same as 
before the disconnection). (Input for set, Output for get) Performs a 
set_term_type control order to inform the rest of the system of the change 
in terminal type. 



pad 



NOTES 



reserved for future expansion and must be "0"b. 



The get_window_status and get_window_status control orders are available from 
command level and as active functions with the following io_call commands: 

io_call control wi ndow_swi tch get_wi ndow_status status_key_l 

{status_key_2} N 
io_call control wi ndow_swi tch set_wi ndow_status status_key_l 

{status_key_N} 

where status_key_N is either screen_invalid, asynchronous_change, ttp_change, or 
reconnection. 



get_capabilities 

returns information about the generic capabilities of the terminal. These are the 
"raw" physical characteristics of the terminal. The video system may simulate 
those that are lacking. For example, the system simulates insert and delete 
characters, but does not simulate insert and delete lines. The info ptr should 
point to the following structure (declared in terminal_capabilities.incl.pll): 



del 1 capab i 1 i t i es_i nf o 

2 version 

2 screensize, 
3 columns 
3 rows 

2 flags, 

3 scrol l_reg ion 
3 insert_chars 
3 insert_mode 
3 delete_chars 
3 overpr i nt 
3 pad 

2 1 i ne_speed 



al i gned based (capab i 1 i t i es_i nf o_ptr) , 
fixed bin, 

fixed bin, 
f i xed bin, 



) unal , 
) unal , 
) unal , 
) unal , 
) unal , 
28) unal , 



xed bin, 
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STRUCTURE ELEMENTS 



version 

is the version number of this structure. (Input) It must be 
capabilities_info_version_l, also declared in the include file. 

columns 

is the number of columns on the terminal. (Output) 

rows 

is the number of rows (lines) on the terminal. (Output) 
scroll_region 

is true if the terminal is capable of scrolling, with insert and delete lines. 
(Output) 

insert_chars 

is true if the insert_chars function is supported. (Output) 
insert_mode 

is true if the terminal is capable of going into and out of insert mode. 
(Output) 

delete_chars 

is true if the delete chars function is supported. (Output) 
overprint 

is true if the terminal is capable of printing overstrike characters. (Output) It 
is currently always set to "0"b (false). 

pad 

reserved for future expansion and must be "0"b. 
line_speed 

is the speed of the communications channel to the terminal, in characters per 
second. (Output) 

reset_more 

causes MORE Processing to be reset. All lines on the window may be freely 
discarded without querying the user. 

get_editing_chars 

is identical to the operation supported by the tty_ I/O module. 

set_editing_chars 

is identical to the operation supported by the tty_ I/O module. 
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NOTES 

The get_editing_chars and set_editing_chars control orders are available from command 
level and as active functions with the following io_call commands: 

io__call wi ndow_swi tch get_edi t i ng_chars 

io__call control wi ndow_swi tch set_ed i t i ng_chars erase_k i 1 l_characters 



get_more_responses 

. returns information about the acceptable responses to MORE processing. The info 
pointer should point to the following structure (declared in 
window_control_info.incl.pll): 



del 1 more_responses_i nf o 
2 version 
2 n_yeses 
2 n_noes 
2 yeses 
2 noes 



aligned based (more_responses_i nf o_ptr) , 
f i xed bin, 
fixed bin, 
f ixed bin, 

char (32) unaligned, 
char (32) unaligned; 



STRUCTURE ELEMENTS 



version 

is the version number of this structure and must be set to 
more_responses_info_version_l, also declared in the include file. (Input) 

n_yeses 

is the number of different affirmative responses, from zero to 32. (Output) 
n_noes 

is the number of different negative responses. (Output) 

yeses 

is the concatenation of all the affirmative responses. (Output) Each response 
is one character. Only the first "n_yeses" are valid. 

noes 

is the concatenation of all negative responses. (Output) Each response is one 
character. Only the first "n_noes H are valid. 

set_more_responses 

sets the responses. The data structure is the same as the one used for the 
"ge t_more_responses" order except that all fields are Input. At most, 32 yeses and 
32 noes may be supplied. It is highly recommended that there be at least one 
yes, so that output may continue. The "yes" and "no" characters must be distinct. 
If they are not, the error code video_et_$overlapping_more_responses is returned, 
and the responses are not changed. 
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NOTES 

The get_more_response and set_more_response control orders are available from 
command level and as active functions with the following io_call command: 

io_call control wi ndow_swi tch get_more_responses 
io_call control wi ndow_swi tch set_more_responses yes_responses 
no_responses 

where the yes_responses and no_responses will be used as arguments to the 
get_more_responses control order. If either of the response strings contains blanks or 
special characters, it must be quoted. 

get_more_prompt set_more_prompt 

sets the prompt displayed when a more break occurs. The current more responses 
can be displayed as part of the more prompt, by including the proper ioa_ 
control codes as part of the prompt string. For example the default video system 
more prompt string is "More? ( A a for more; A a to discard output.)". With the 
default more responses of carriage return for more and the delete for discard, the 
final string displayed is "More (RETURN for more; DEL to discard ouiput.)." 
The info pointer should point to the following structure (declared in 
window_control_inf o.incl.pll): 

del 1 more_prompt_i nf o aligned based (more_prompt_i nf o_ptr) , 
2 vers i on char (8) , 

2 more_prompt char (80) ; 



STRUCTURE ELEMENTS 



version 

is the version number of this structure (currently more_prompt_info_version_l). 
(Input) 

more_prompt 

is the ioa_ control string to serve as the more prompt. (Input for set, 
Output for get) 
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The get_more_prompt and set_more_prompt control orders are available from command 
level and as active functions with the following io_call command: 

io_call control wi ndow_swi tch get_more__prompt 

io_ca!1 control wi ndow_swi tch set_more_prompt prompt_str i ng 

where window_switch is a valid window_io_ switch and prompt_string is the ioa_ 
control string described above. 

get_more_handler set_more_handler 

Sets the handler for video system more breaks to the specified routine. The info 
pointer should point to the following structure (declared in window_control_io.incl.pll): 

del 1 more_hand 1 er_i nf o aligned based (more_handl er_i nfo_ptr) , 

2 version fixed bin, 

2 flags unal igned, 

3 old_handler_val id bit(l), 

3 pad ~ bit (35) , 

2 more_handl er entry (pointer, bit ( 1 ) aligned), 

2 ol d_more_hand 1 er entry (pointer, bit(l) aligned); 

del (more_hand 1 er__i nf o_vers i on_3) ; 

fixed bin internal static options (constant) init (3); 



STRUCTURE ELEMENTS 



version 

is the version number of this structure, and must be set to 
more_handler_info_version_3 (also declared in the include file). (Input) 

more_handler 

is the entry to be called at a more break. (Input for set) (Output for get) It 
will be passed two arguments, described below. 

old_handler_valid 

is a flag specifying whether some other user-supplied more handler was in 
effect when the order call was made. (Output) (This can only be used with 
get.) 

old_more_handler 

is the user supplied entry that was acting as more handler before the order 
call was made. (Output) Its value is only defined if the old_handler_valid 
flag is on. (This can only be used with get.) 

The more handler routine is called with two arguments. The first is a pointer to 
a structure containing information of interest to a more handler (see below), and 
the second is a flag which the more handler sets to indicate whether or not 
output should be flushed OT'b to continue output, "0"b to flush output). 
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The structure can be found in the include file window_more_handler.incl.pll, and 
is declared as follows: 



del 1 more_info 
2 version 
2 more_mode 
2 wi ndow_iocb_prt 
2 more_prompt 
2 more_responses, 
3 n_yeses 
3 n_noes 
3 more_yeses 

3 more_noes 



aligned base (more_i nf o_ptr) , 
fixed bin, 

fixed bin, /* which flavor */ 

pointer, /* for window that MORE'd */ 

character (80) , /* MORE? */ 



fixed bin, 
f i xed bin, 
character (32) 

character (32) 



unal i gned, 

/* at most 32 yeses */ 
unal igned; 



* 

STRUCTURE ELEMENTS 



version 

is the version number of the structure (declared as more_handler_info_version_2 
in the include file). (Input) 

window_iocb_ptr 

is a pointer to the iocb for the window in which the more break occurred. 
(Input) Prompt output should be written to this switch, and responses should 
be read from it. 

more_mode 

is the current more mode. (Input) Constants for the different more modes 
are declared in the include file window_io_attach_data.incl.pll. 

more_prompt 

is the current more prompt (Input) This is the string "More? ( A a for more; 
A a to discard output)" and is user-settable. 

more_responses 

is the current set of more responses, and is declared similarly to the 

more_responses_info structure in the get_more_responses order description 
above. (Input) 
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NOTES 

The get_more_handler and set_more_handler control orders are available from 
command level and as active functions with the following io_call command: 

io_call wi ndow_swi tch get_more_handler 

io_ca11 wi ndow_swi tch set_more_handl er more_handl er 

where more_handler is the entryname of the routine to be used as the more handler 
routine. The name is converted to an entry using the user's search rules and is then 
used as described in the set_more_handler control order. 

get_break_table set_break_table 

break table determines action of the get_echoed_chars, get_unechoed_chars, and 
write_sync_read entry points of the window_ subroutine. The array "breaks" has a 
1 for each character that is to be considered a break. By default, the break table 
has "l"b for all the nonprin table characters, and "0"b elsewhere. Applications that 
set the break table must be careful to reset it afterwards, and establish an 
appropriate cleanup handler. 

del 1 break_tabl e_i nf o aligned based (break_tabl e_ptr) , 
2 versions fixed bin, 

2 breaks (0:127) bit (1) unaligned; 



STRUCTURE ELEMENTS 



versions 

must be set by the caller to break_table_info_version_l. (Input) 
breaks 

has a *T'b for each character that is a break character. (Input/Output) 
reset_more_handler 

cancels the last user-defined more_handler. The reset_more_handler control order 
is available from command level with the following io_call command: 

io call control window switch reset more handler 
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get_output_eoriversion 

this order is used to obtain the current contents of the specified table. The 
info_ptr points to a structure like the one described for the corresponding "set" 
order below, which is filled in as a result of the call (except for the version 
number, which must be supplied by the caller). If the specified table does not 
exist (no translation or conversion is required), the status code error_table_$no_table 
is returned. 



set_output_conversion 

provides a table to be used in formatting output to identify certain kinds of 
special characters. The info_ptr points to the following structure (declared in 
tty_convert.incl.pll). If the info_ptr is null, no transaction is to be done. 



del 1 cv_trans_struc 
2 version 
2 default 
2 cv_trans 
3 value 



al i gned 
fixed bin, 
fixed bin, 
al i gned 
(0:255) fixed 



bin (8) una 1 i gned 



STRUCTURE ELEMENTS 



version 

is the version number of the structure. It must be 2 and declared in 
tty_con ver t. incl. pll . 

default 

indicates, if nonzero, that the table is the one that was in effect before 
video was invoked. 

values 

are the elements of the table. This table is indexed by the value of a typed 
input character, and the corresponding entry contains the ASCII character 
resulting from the translation. 
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get_special 

is used to obtain the contents of the special_chars table currently in use. The 
info_ptr points to the following structure (defined in tty_convert.incl.pll): 

del 1 get_special_info_struc aligned 
2 area_ptr ptr, 
2 table_ptr ptr; 



STRUCTURE ELEMENTS 



area_ptr 

points to an area in which a copy of the current special_chars table is 
returned. (Input) 

table_ptr 

is set to the address of the returned copy of the table. (Output) 
set_special 

provides a table that specifies sequences to be substituted for certain output 
characters, and characters that are to be interpreted as parts of escape sequences 
on input. Output sequences are of the following form (defined in tty_converLincl.pll): 

del 1 c_chars based aligned, 

2 count fixed bin (8) unaligned, 

2 chars (3) char (1) unaligned; 



STRUCTURE ELEMENTS 



count 

is the actual length of the sequence in characters (0<= count <=3). If count 
is zero, there is no sequence. 
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chars 



are the characters that make up the sequence. The info_ptr points to a 
structure of the following form (defined in tty_convert.incl.pll): 



del 1 speci al_chars_struc a 

2 version f 

2 default f 
2 speci al_chars 



igned based, 
xed bin, 
xed bin, 



3 


nl_seq 


al i gned 1 


i ke 


c_chars, 


3 


cr_seq 


al i gned 1 


i ke 


c_chars , 


3 


bs_seq 


al i gned 1 


i ke 


c_chars , 


3 


tab_seq 


al i gned 1 


i ke 


c_chars , 


3 


vt_seq 


al i gned 1 


i ke 


c_chars , 


3 


f f_seq 


a 1 i gned 1 


i ke 


c_chars, 


3 


pr i nter_on 


al i gned 1 


i ke 


c_chars , 


3 


pr i nter_of f 


aligned 1 


i ke 


c_chars , 


3 


red_r i bbon_sh i ft 


al i gned 1 


i ke 


c_chars , 


3 


black_r ibbon_shi f t 


aligned 1 


i ke 


c_chars , 


3 


end_of_page 


al i gned 1 


i ke 


c_chars , 


3 


escape_l ength 


f i xed b i n 


, 




3 


not_ed i ted_escapes 


(sc_escape_l en refer 






(speci al_ 


chars .escape_l ength) ) 



3 ed i ted_escapes 



i nput_escapes 
h 1 en 
h str 



3 i nput_resul ts 
k pad 
h str 



1 i ke c_chars , 
(sc_escape_l en refer 
(spec i al_chars .escape_l ength) ) 

1 i ke c_chars , 
al i gned , 

fixed bin (8) unaligned, 

char (sc_i nput_escape_l en refer 

(spec i a ]_cnar s . i nput_es capes . 1 en) ) 

unal i gned, 
al i gned, 

bi t (9) unal i gned, 
char (sc_i nput_escape_l en refer 
(special_chars. i nput_escapes . len) ) 
una 1 i gned ; 
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NOTES 

Video ignores cr_seg, bs_seg, tab_seg, vt_seg, ff_seg, printer_on, printer_off, end_of_page, 
input_escapes, and input results. 

STRUCTURE ELEMENTS 



version 

is the version number of this structure. It must be 1. 
default 

indicates, if nonzero, that the default values for the current terminal type and 
baud rate are to be used and that the remainder of the structure is to be 
ignored. 

nl_seq 

is the output character sequence to be substituted for a newline character. 
The nl_seq. count generally should be nonzero. 

cr_seq 

is the output character sequence to be substituted for a carriage-return 
character. If count is zero, the appropriate number of backspaces is 
substituted. However, either cr_seq.count or bs_seq.count should be nonzero 
(i.e., both should not be zero). 

bs_seq 

is the output character sequence to be substituted for a backspace character. 
If count is zero, a carriage return and the appropriate number of spaces are 
substituted. However, either bs_seq.count or cr_seq.count, should be nonzero 
(i.e., both should not be zero). 

tab_seq 

is the output character sequence to be substituted for a horizontal tab. If 
count is zero, the appropriate number of spaces is substituted. 

vt_seq 

is the output character sequence to be substituted for a vertical tab. If count 
is zero, no characters are substituted. 

ff_seq 

is the output character sequence to be substituted for a formfeed. If count is 
zero, no characters are substituted. 
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printer_on 

is the character sequence to be used to implement the printer_on control 
operation. If count is zero, the function is not performed. 

printer_off 

is the character sequence to be used to implement the printer_off control 
operation. If count is zero, the function is not performed. 

red_ribbon_shift 

is the character sequence to be substituted for a red-ribbon-shif t character. 
If count is zero, no characters are substituted. 

black_ribbon_shif t 

is the character sequence to be substituted for a black_ribbon_shift character. 
If count is zero, no characters are substituted. 

end_of_page 

is the character sequence to be printed to indicate that a page of output is 
full. If count is zero, no additional characters are printed, and the cursor is 

„♦ <-u „ 3 ~e tu„ i„„* i; 

id l ai lug tiiu. \ji uit laoi niifc. 

escape_length 

is the number of output escape sequences in each of the two escape arrays. 
not_edited_escapes 

is an array of escape sequences to be substituted for particular characters if 
the terminal is in " A edited" mode. This array is indexed according to the 
indicator found in the corresponding output conversion table (see the 
description of the set_output_conversion order above). 

edited_escapes 

is an array of escape sequences to be used in edited mode. It is indexed in 
the same fashion as not_edited_escapes. 

input_escapes 

is a string of characters each of which forms an escape sequence when 
preceded by an escape character. 

input_results 

is a string of characters each of which is to replace the escape sequence 
consisting of an escape character and the character occupying the corresponding 
position in input_escapes. 
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get_token_characters, set_token_characters 

changes the set of characters that are used by the video system input line editor 
to define a word for such requests as ESC DEL. The set of characters supplied 
in the structure replace the existing set of characters. The info_ptr points to the 
following structure (declared in window_control_info.incl.pll): 

del 1 token_characters_i nf o aligned based 

(token_characters_i nf o_ptr) , 
2 version char (8) , 

2 token_characters_count fixed bin, 
2 token_characters char (128) unaligned; 



STRUCTURE ELEMENTS 



version 

is the version string for this structure. (Input) Its current value is 
token_characters_info_version_l, also declared in the include file. 

token_characters_count 

is the number of characters in the token_characters string. (Input) 

token_characters 

is a character string containing the new set of token characters. (Input) 

NOTES 

The set_token_characters and get_token_characters control orders are available from 
command_level and as active functions with the following io_call commands: 

io_call control wi ndow_swi tch get_token_characters 

io_call control wi ndow_swi tch set_token_characters token_char_str i ng 

where token_char_string is a character string containing the new set of token 
characters. get_token_character returns its result as a string if it was invoked as an 
active function, otherwise it prints out the token characters. 



get_editor_key_bindings 

returns a pointer to the line_editor_key_binding structure describing the key 
bindings. io_call support points out the pathname of each editor routine, listing 
only the names of builtin requests in capital letters, with the word "builtin" in 
parentheses. The control order prints or returns current information about the key 
bindings. Use the set_editor_key_bindings control order to change the bindings. 
This control order prints or returns current information about the key_bindings. 
Use the set_editor_key_bindings control order to change the bindings. 
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The info_ptr points to the 
window_control_inf o.incLpll): 

del 1 get_ed i tor_key_bi nd i ngs_i nf o 

2 version 
2 flags, 

3 entire_state 

3 mbx 

2 key_b i nd i ng_i nf o_ptr 
2 ent i re_state_ptr 



following structure (declared in 



al i gned based 

(get_ed i tor_key_b i nd i ng_i nf o_ptr) , 
char (8) , 

bit (1) unal i gned, 
bi t (35) unal igned, 
ptr, 
ptr; 



STRUCTURE ELEMENTS 



version 

is get_editor_key_binding_info_version_l. (Input) 
entire_state 

is "l"b if the entire state is desired, "0"b if only information about certain 
keybindings is. desired. (Input) 

key_binding_inf o_ptr 

if entire_state = "0"b, then this points to a line_editor_key_binding_structure. 
(Input) The bindings component of this structure is then filled in based upon 
the value of each key_sequence supplied. 

entire_state_ptr 

is set to point to the "state" of the key bindings, if entire_state = "i"b. 
(Output) This is suitable input to the set_editor_key_bindings control order. 

NOTES 

The get_editor_key_bindings control order is available from command level and as an 
active function with following io_call command: 

io_call control wi ndow_swi tch get_ed i tor_key_b i nd i ngs 

The get_editor_key_bindings control order prints or returns information about a key 
binding. When you use it as an active function the information is returned in a form 
suitable as arguments to the set_editor_key_bmdings control order. 
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set_editor_key_bindings 

A line editor routine is bound to a sequence of keystrokes via the set_editor_key 
bindings control order. The sequence of characters that triggers an editor request 
may be of any length, with multiple-key sequences working like the Emacs prefix 
characters. This allows the use of terminal function keys (which often send three 
or more character sequences) to invoke line editor requests. More than one 
binding can be set in one invocation of this control order. 

The info_ptr points to the following structure (declared in 
window_control_inf o.inclpll): 

del 1 set__edi tor_key_bi ndi ngs_info aligned based 

(set_ed i tor_key_b i nd i ngs_i nf o_ptr) , 
2 version char (8) , 

2 flags, 

3 replace bit (1) unaligned, 

3 update bit (1) unaligned, 

3 pad bit (3^) unaligned. 

2 key_b i nd i ng_i nf o_ptr ; 



STRUCTURE ELEMENTS 



version 

is the version of the structure. (Input) It must be 
set_editor_key_bindings_info_version_l. 

replace 

if "l"b then key_binding_info is considered to be returned by a previous 
get_editor_key_bindings operation with entire_state = "l"b and will be used to 
replace the keybinding state of the editor. (Input) 

update 

if "l"b then key_binding_inf o_ptr is considered a pointer to a 
line_editor_key_binding_info structure, which will be used to update the 
keybinding state of the editor. (Input) 

Note: only one of replace and update may be true, but at least one of them 
must be true. 

key_binding_info_ptr 

is a pointer received from get_editor_key bindings operation or a pointer to a 
line_editor_key_binding_info structure, depending on the value of the replace 
and update flags. (Input) 

Notes on freeing: The video system's internal data structures are freed at the 
following times: video system revocation and when a set_editor_key_bindings 
control order with replace = "l"b is done. 



3-281 



AG93-05 



window_io_ window_io. 



NOTES 

The set_editor_key_bindings control order is available from command level and as an 
active function with the following io_call command: 

io_call control wi ndow_swi tch set_ed i tor_key_b i nd i ngs key_sequencel 
{user_rout i nel} {control_args 1 } ... key_sequenceN 
{user__rout i neN} {control_argsl} {control_argsN} 

where user_routine is the name of a user-written editor request. 

control args are: 

-external user_routine 
-builtin bui 1 ti n_request_name 
-numarg_act ion numarg_act i on_name 

The line_editor_key_bindings_info structure is described in Section 7. 

At least one user_routine or one of -external /-builtin must be specified for each key 
| sequence, with the rightmost editor request specifier taking precedence (for example, io 
| control window_switch set_editor_key_binings foo -builtin FORWARD_word,) will bind 

control -a to the forward word builtin, not the user routine foo. 



numarg_action_name 

the type of automatic numeric argument to be taken when the editor routine is 
invoked, must be one of the following and can only be given for external editor 
routines 

REPEAT 

| (the default is PASS). This can be entered in upper or lower case. Call the user 
routine n times, where n is the numeric argument supplied by the user. 

REJECT 

ring the terminal bell and don't call the user routine if a numeric argument is 
given. 

PASS 

pass any numeric argument to the user routine, without any other action. 
IGNORE 

same as PASS but implies the user routine will not make use of the numeric 
argument. 

J -name STR 

specifies the name of the editor command being assigned to the key. If this is 
the null string, then a default name is used (for builtins this is the name of the 
builtin, otherwise it is segnameSentrypoint). STR must be quoted if it contains 
whitespace. 
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-description STR 

specifies a description string to be associated with the key binding. If this is the 
null string, a default description is used. The defaults can be found in the 
include file window_editor_values.incl.pll. STR must be quoted if it contains 
whitespace. 

-info_pathname PATH 

specifies an info segment pathname to be associated with this key binding. This 
info segment is expected to have more information about the editor_routine. If 
this is not specified, it defaults to >doc>info>video_editing.gi.info if -builtin, 
otherwise no info segment is associated with the key. The info suffix is assumed 
on PATH. 

MODES OPERATION 

The modes operation is supported by window_io_. The recognized modes are listed 
below. Some modes have a complement indicated by the circumflex character ( A ) that 
turns the mode off (e.g. A more). For these modes, the complement is displayed with 
that mode. Some modes specify a parameter that can take on a value (e.g. 
more_mode). These modes are specified as MODE= VALUE, where MODE is the name 
of the mode and VALUE is the value it is to be set to. Parameterized modes are 
indicated by the notation (P) in the following description: 

more, A more 

Turns MORE processing on. Default is on. If A pl is set before you invoke the 
video system, A more will be set when you invoke the video system. 

more_mode = STR 

controls behavior when the window is filled. The value for STR may be one of 
the following: 

clear 

the window is cleared, and output starts at the home position. 

fold 

output begins at the first line and moves down the screen a line at a time 
replacing existing text with new text. Prompts for a MORE response when it 
is about to overwrite the first line written since the last read or MORE 
break. 

scroll 

lines are scrolled off the top of the window, and new lines are printed in 
the space that is cleared at the bottom of the screen. This is the default for 
full width windows on all terminals capable of scrolling. 

wrap 

output begins at the first line and moves down the screen a line at a time 
replacing existing text with new text. Prompts for a MORE response at the 
bottom of every window of output. This is the default for all terminals that 
are incapable of scrolling or when using partial width windows. 
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vertsp, A vertsp 

is only effective when more mode is on. When vertsp mode is on, output of 
a FF or VT will cause an immediate MORE query. When you invoke the 
video system, it copies the current setting of this mode before attaching the 
window_io_ module. The default is A vertsp. 

rawo, A rawo 

causes characters to be output with no processing whatsoever. The result of 
output in this mode is undefined. 

can, A can 

causes input lines to be canonicalized before they are returned. When you 
invoke the video system, it copies the current setting of this mode before 
attaching the window_io_ module. The default is on. 

ctl_char, A ctl_char 

specifies that ASCII control characters that do not cause newline or linefeed 
motion are to be accepted as input except for the NUL character. If the 
mode is off all such characters are discarded. When you invoke the video 
system, it copies the current setting of this mode before attaching the 
window_io_ module. The default is off. 

edited, A edited 

suppresses printing of characters for which there is no defined Multics 
equivalent on the device referenced. If edited mode is off, the 9-bit octal 
representation of the character is printed. When you invoke the video system, 
it copies the current setting of this mode before attaching the window_io_ 
module. The default is off. 

erkl, A erkl 

controls the editing functions of get_line. When you invoke the video system, 
it copies the current setting of this mode before attaching the window_io_ 
module. The default is on, which allows erase and kill processing and the 
additional line editor functions. 

esc, A esc 

controls input escape processing. When you invoke the video system, it copies 
the current setting of this mode before attaching the window_io_ module. 
The default is on. 

rawi, A rawi 

acts as a master control for can, erkl, and esc. If this mode is on, none of 
the input conventions are provided. The default is on. 

11 = STR 

is the width of the window, in characters, and it can only be changed with 
the set_window_info control operation. 
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pi = STR 

is the height of the window (i.e., number of lines), and it can only be 
changed with the set_window_info control operation. 

red, A red 

controls interpretation of red shift and black shift characters on output. 
When you invoke the video system, it copies the current setting of this mode 
before attaching the window_io_ module. The default is A red, which ignores 
them. In red mode, the character sequence given in the TTF is output The 
effect is undefined and terminal-specific. In some cases, "red shifted" output 
appears in inverse video, but this is not guaranteed. 

CONTROL OPERATIONS FROM COMMAND LEVEL 

Those control operations which require no info_ptr and those additional orders 
described above may be performed from command level using the io_call command, as 
follows: 

io call control switch name control order 



ARGUMENTS 

switch_name 

is the name of the I/O switch. 

control_order 

can be any control order described above under "Control Operation" that can 
accept a null info_ptr. 



Name: xmodem io 

The xmodem__io_ I/O module is used to transfer files between a Multics process and 
a microcomputer that runs the XMODEM data transfer protocol. It performs 8-bit 
stream I/O over an asynchronous communications channel using the xmodem protocol. 



Entry points in this module are not called directly by users; rather the module is 
accessed through the I/O system. 

ATTACH DESCRIPTION 

xmodem_io_ switch {-control_args} 
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ARGUMENTS 
switch 

is the name of the target I/O switch. The switch must be open for 
stream_input_outpuL The I/O module for the target switch must be supported by 
the timed_io_ module. The user is responsible for setting any modes required by 
the xmodem protocol. For example, modes for the user_i/o switch would be: 
"no_outp, 8bit,breakall, A echoplex,rawi, A crechojf echo, A tabecho,rawo" 

CONTROL ARGUMENTS 

-error_detecting_code STR, -edc STR 

specifies the error-detecting code to be used for the file transfer, where STR may 
be one of the following: 

check_sum, cs 

specifies that the checksum error-detecting code is to be used for the file 
transfer. 

cyclic_redundancy_code, crc 

specifies that the CRC-CCITT error-detecting code is to be used for the file 
transfer. Note, because it is the receiver that determines the type of 
error-detecting code, this control argument is incompatible with the stream_output 
opening mode. 

Default is check_sum. 

OPEN OPERATION 

The xmodem_ I/O module supports the stream_input and stream_output opening 
modes. 

CLOSE OPERATION 

When opened for stream_output, the close entry transmits any remaining data in the 
internal buffer before closing the switch. If there are less than 128 bytes in the 
buffer, the buffer is filled with the NUL ASCII character, 000 (octal), before 
transmission. See Buffering below. 

PUT CHARS OPERATION 

The put_chars entry splits the data to be written into 128-character blocks. The 
appropriate xmodem control characters are added to the beginning and end of each 
block. For further explanation of the put_chars entry, see the iox_$put_chars entry. 

GET CHARS OPERATION 

The get_chars entry reads and decodes xmodem blocks, removes the xmodem control 
characters, and returns the message text to the caller's buffer. For further explanation 
of the get_chars entry, see the iox_$get_chars entry. 
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GET LINE OPERATION 

The get_line entry reads and decodes xmodem blocks, removes the control characters, 
and returns the message text to the caller's buffer. Characters are returned until either 
a newline character is placed in the buffer or the buffer is filled. For further 
explanation of the get_line entry, see the iox_$get_line entry. 

CONTROL OPERATION 

This operation is not supported. 

MODES OPERATION 

This operation is not supported. 

BUFFERING 

The xmodem protocol uses 128 data characters per packet. Data that is not a multiple 
of 128 characters is stored in an internal buffer by the xmodem_io_ I/O module. 
Thus, those users concerned with efficiency should provide a multiple of 128 data 
characters for I/O operations. 

NOTES 

No particular line speed is guaranteed when transferring data between Multics and a 
microcomputer. Line speed is dependent on the microcomputer and the load of the 
FNP and communication system for Multics. Due to the nature of the XMODEM 
protocol, files may not be successfully transferred to Multics over high-speed lines. 
The actual limit depends on the site configuration and current load. 

DEFINITIONS 



<soh> 01 (HEX) 01 (OCT) 

<eot> 04 (HEX) 04 (OCT) 

<ack> 06 (HEX) 06 (OCT) 

<nak> 15 (HEX) 25 (OCT) 
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TRANSMISSION MEDIUM LEVEL PROTOCOL 
Asynchronous, 8 data bits, no parity, one stop bit. 

There are no restrictions on the contents of the data being transmitted. Any kind of 
data may be sent binary, ASCII, etc. No control characters are looked for in the 
128-byte data messages. 



MESSAGE BLOCK LEVEL PROTOCOL 



The standard transmission portion of a message block is a 132 character block without 
framing characters. Each block of the transfer looks like: 

<S0H><blk #><255-blk #><..128 data bytes.. ><edc> where: 
<S0H> = 01 (Hex) . 

<b 1 k #> = binary number, starts at 01 increments by 1 
and wraps OFF (Hex) to 00 (Hex) . 

<255 _ blk #> = The one's complement of the block number. 

<edc> = A one-character checksum or two-character CRC-CCiTT. 

The checksum is the sum of the data bytes only. The 
CRC-CCITT is a 1 6-bit remainder obtained by dividing 

16 12 5 

the data bit string by the polynomial X +X +X +1. 



File Level Protocol 

When writing programs that implement the XMODEM protocol, users should follow 
the procedures listed below: 

In both sending and receiving programs, all errors should be retried ten times. 



THE RECEIVING PROGRAM 



The receiver should have a 10-second timeout and send a <nak> every time it times 
out. The first timeout that sends a <nak> signals the transmitter to start. 

Once into receiving a block, the receiver must go into a one-second timeout for each 
character and the checksum. If a valid block is received, the receiver must transmit 
an <ack>. For invalid blocks, a <nak> must be transmitted. 
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The Sending Program 

The sender should start transmission upon receipt of a <nak> from the receiver. If 
the block is received successfully (i.e., the receiver sends an <ack>), the next block 
should be sent. If the receiver responds with a <nak>, the transmission has failed, and 
the sender should retransmit the last block. When the sender has no more data, he 
should send an <eot> and await an <ack>. If it does not get one, the sending 
program should repeat the <eot>. 
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OBSOLETE FUNCTIONS 



This section contains descriptions of those functions that have been functionally 
replaced with other functions whose usage is preferred; The following are documented 
here because they are still called by older programs: 



Obsolete Function 


Replacement 


decode_clock_value_ 


date_time_$f rom_clock 


encode_clock_value_ 


date_time_$to_clock 


hcs„$del_dir_tree 


delete_$path 


hcs_$delentry_file 


delete_$path 


hcs_$delentry_seg 


delete_$ptr 


hcs_$set_bc_seg 


terminate_file_ 


hcs_$terminate_f ile 


term_ 


hcs_$terminate_name 


term_$refname 


hes_$terminate_noname 


terminate_file_ 


hcs_$terminate_seg 


term_$seg_ptr 


hcs_$truncate_seg 


terminate_file_ 


ipc_$create_ev_chn 


ipc_$create_event_channel 


ipc_$decl_event_call_chn 


ipc_$create_event_channel 


link_unsnap_ 


term_$unsnap 
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Name: decode clock value 

NOTE: All entrypoints in decode_clock_value_ are replaced by date_time_$from_clock; 
decode_clock_value_ is supported for compatibility only. 



The decode_clock_value_ subroutine takes a given system clock reading and returns the 
month, the day of the month, the year, the time of day, the day of the week, and 
the local time zone. 

USAGE 

del decode_clock_yalue_ entry (fixed b 1 n (7 1 ) i fixed bin, fixed bin, 
fixed bin, fixed bin(7D, fixed bin, char (3) ) ; 

call decode_clock_value_ (clock, month, dom, year, tod, dow, zone); 
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ARGUMENTS 
clock 

is the system clock value to be decoded. (Input) 
month 

is the month (January = 1 December - 12). (Output) 

dom 

is the day of the month, i.e., 1 to 31. (Output) 

year 

is the year, e.g., 1982. (Output) 

tod 

is the time of day (number of microseconds since midnight). (Output) 

dow 

is the day of the week (Monday = 1, Sunday - 7). (Output) 

zone 

is a three-character lowercase abbreviation of the time zone currently used by this 
process (for example, mst, edt). (Output) 

NOTES 

If the clock value does not lie within the 20th century, then zero values are returned 
for month, dom, year, tod, and dow. 



Entry: decode clock value $date time 

This entry point is given a system clock reading and returns the month, the day of 
the month, the year, the hour, the minute, the second, the microseconds within a 
second, and the day of the week. The time zone in which the decoded clock reading 
is expressed may be given as input, or the current time zone can be used. 

USAGE 

declare decode_clock_value_$date_time entry (fixed bin (71), fixed bin, 
fixed bin, fixed bin, fixed bin, fixed bin, fixed bin, 
fixed bin(7D> fixed bin, char (3) , fixed bin(35))» 

call decode_clock_value_$date_t ime (clock, month, dom, year, hour, 
minute, second, microsecond, dow, zone, code); 
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ARGUMENTS 
clock 

is the system clock value to be decoded. (Input) 
month 

is the month (January = 1, December = 12). (Output) 

dom 

is the day of the month, i.e., 1 to 31. (Output) 

year 

is the year, e.g., 1982. (Output) 

hour 

is the hour of the day (midnight = 0, 11 PM = 23). (Output) 
minute 

is the minute of the hour, i.e., 0 to 59. (Output) 



is the second of the minute, i.e., 0 to 59. (Output) 

microsecond 

is the microsecond within a second. (Output) 

dow 

is the day of the week (Monday = 1 Sunday = 7). (Output) 

zone 

is a three-character abbreviation of the time zone in which the decoded clock 

value is expressed. (Input or Output) 

Input 

is one of the zone abbreviations given in the table of time zones, or is a 
null character string. A zone abbreviation may be in uppercase or lowercase. 
If a null string is given, the time zone currently used by this process is 
assumed. 
Output 

is a three-character lowercase abbreviation of the current time zone used by 
this process if a null character string was given as input. 

code 

is a standard system status code. (Output) It may be one of the following: 
error_table_$bad year 

the clock reading does not represent a date within the 20th century. 
error_table_$unknown_zone 

the specified time zone abbreviation is not in the table of time zones. 
error_table_$unimplemented_version 

the current version of the table of time zones is not implemented by 

decode_clock_value_. 
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Name: encode clock value 

NOTE: encode_clock_value_ is replaced by date_time_$to_clock; encode_clock_vaiue_ is | 
supported for compatibility only. j 



The encode_clock_value_ subroutine takes a given month, day of the month, year, 
hour of the day, minute, second, microsecond, and time zone and returns a system 
clock reading. When given a day of the week, it performs an optional check on the 
clock reading to ensure that it falls on the given day. 

A system clock reading is encoded as the number of microseconds from 
January 1, 1901 0000.0, Greenwich Mean Time (GMT) to the given date, time, and 
time zone. 

USAGE 

declare encode_c 1 ock_va 1 ue_ entry (fixed bin, fixed bin, fixed bin, 
fixed bin, fixed bin, fixed bin, fixed bin (71). fixed bin, 
char (3), fixed bin(7D, fixed bin(35)); 

call encode_clock_value_ (month, dom, year, hour, minute, second, 
microsecond, dow, zone, clock, code); 

ARGUMENTS 

month 

is the month (January = 1, .... December = 12). (Input) 

dom 

is the day of the month, i.e., 1 to 31. (Input) 

year 

is the year, e.g., 1982. (Input) 

hour 

is the hour of the day (midnight = 0, 11 PM - 23). (Input) 
minute 

is the minute of the hour, i.e., 0 to 59. (Input) 
second 

is the second of the minute, i.e., 0 to 59. (Input) 
microsecond 

is the number of microseconds that are added to the clock reading encoded from 
the given month, dom, year, hour, minute, and second. (Input) 

dow 

is the day of the week (0 = no day of week checking, 1 = Monday, 7 = Sunday). 
(Input) 
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zone 

is a three-character abbreviation of the time zone in which the given day of the 

month and hour are expressed. (Input or Output) 

Input 

is one of the zone abbreviations given in the table of time zones (see the 
convert_date_to_binary_ subroutine), or is a null character string. A zone 
abbreviation may be given in uppercase or lowercase. If a null string is 
given, the current time zone used by the process is assumed. 
Output 

is a three-character lowercase abbreviation of the current time zone used by 
the process if a null character string was given as input. 

clock 

is the encoded system clock reading. (Output) 

code 

is a system status code. (Output) It can be one of the following: 
error_table_$bad_date 

the date represented by month, dom and year is an invalid date, e.g., 

2/29/77= 
error_table_$bad_day_of_week 

the returned clock reading does not fall on the given day of the week, or 

dow is not a number from 0 to 7. 
error_table_$bad_time 

the time represented by hour, minute, second, and microsecond is invalid, 

e.g., 23:60 or negative time values. 
error_table_$unknown_zone 

the specified time zone abbreviation is not in the table of time zones. 
error_table_$unimplemented_version 

the current version of the table of time zones is not implemented by 

encode_clock_value_. 



Entry: encode clock value Soffsets 

NOTE: encode_clock_value_$offsets is replaced by date_time_$offset_to_clock; 
encode_clock_value_$offsets is supported for compatibility only. 



This entry point takes a system clock reading, a day of the week, and year, month, 
day, hour, minute, second, and microsecond, offset values. The offset values may be 
positive, negative, or zero. It returns a clock reading that has been adjusted to fall on 
the given day of the week, and which is then offset by the given number of years, 
months, days, hours, minutes, seconds, and microseconds. 
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encode_clock_value. 



USAGE 

declare encode_clcck_value_$of f sets entry (fixed bin(7D» fixed bin, 
fixed bin, fixed bin, fixed bin, fixed bin, fixed bin, 
fixed bin(7D, fixed bin, char (3) , fixed bin(7D, fixed bin(35)); 

call encode_c 1 ock_va 1 ue_$of f sets (dock__in, month_off, day__off, 
year_pff, hour__off, minute_off, second_off, mi crosec_of f , 
dow_offset, 2one, clock_out, code); 

ARGUMENTS 

clock_in 

is a system clock reading. (Input) 

month_off 

is an offset, in months. (Input) 

day_off 

is an offset, in days. (Input) 

year_off 

is an offset, in years. (Input) 

hour_off 

is an offset, in hours. (Input) 

minute_off 

is an offset, in minutes. (Input) 

second_off 

is an offset, in seconds. (Input) 

microsec_off 

is an offset, in microseconds. (Input) 

dow_off 

is a day of the week offset (0 - no day of week offset, 1 = offset to next Monday, 
7 = offset to next Sunday). (Input) 
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zone 

is a three-character abbreviation of the time zone in which the input clock 
reading is to be interpreted. (Input or Output) The choice of zone may alter 
which day of the week the input clock reading falls on, and may therefore affect 
any day of the week adjustment. 
Input 

is one of the zone abbreviations given in the table of time zones (see the 
convert_date_to_binary_ subroutine), or is a null character string. A zone 
abbreviation may be given in uppercase or lowercase. If a null string is 
given, the current time zone used by the process is assumed. 
Output 

is a three-character lowercase abbreviation of the current time zone used by 
the process if a null character string was given as input. 

clock_out 

is the adjusted clock reading. (Output) 

code 

is a system status code. (See above.) (Output) 
NOTES 

The order in which offsets are applied to the input clock reading can affect the 
adjusted clock reading. The encode_clock_value_$offsets entry point uses the order 
required by the convert_date_to_binary_ subroutine in all cases. The offsets are 
applied in the following order: 

1. Decode the input clock reading into absolute date and time values specified in 
terms of the input time zone. The time zone can alter the day of the week 
the input clock reading falls on, and can therefore change the effect of the 
day of the week offset 

2. Apply any day of the week offset by adding days to the absolute date values 
from step 1 until the date falls on the given day of the week. 

3. Apply any year offset to the absolute date values from step 2. 

4. Apply any month offset to the absolute date values from step 3. If applying 
the month offset results in an invalid date (e.g., 1/31/77 +3 months yields 
4/31/77), then adjust the day of the month to be the last day of the new 
month, taking leap years into account. 

5. Apply the day offset to the absolute date values from step 4. 

6. Apply the hour, minute, second, and microsecond offsets to the absolute time 
values from step 1. 

7. Encode the absolute date values from step 5 and absolute time values from 
step 6 to form the adjusted clock reading. 
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Name: hcs $del dir tree 

This entry point, given the pathname of a containing directory and the entryname of 
a subdirectory, deletes the contents of the subdirectory from the storage system 
hierarchy. All segments, links, and directories inferior to that subdirectory are deleted, 
including the contents of any inferior directories. The subdirectory is not itself 
deleted. For information on the deletion of directories, see the description of the 
hcs_$delentry_file entry point. 

USAGE 

declare hcs_$del_di r_tree entry (char (*) , char (*) , fixed bin (35)); 

call hcs_$del_d i r_tree (dir_name, entryname, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the directory. (Input) 

code 

is a storage system status codc(Output) 
NOTES 

The user must have status and modify permission on the subdirectory and the safety 
switch of all branches in the directory must be off. If the user does not have status 
and modify permission on inferior directories, access is automatically set and processing 
continues. 

If an entry in an inferior directory gives the user access only in a ring lower than 
his validation level, that entry is not deleted and no further processing is done on the 
subtree. For information about rings, see "Intraprocess Access Control" in the 
Programmer's Reference Manual. 
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hcs_$delentry_file 



Name: hcs Sdelentry file 

The hcs_$delentry_file entry point, given a directory name and an entryname, deletes 
the given entry from its containing directory. This entry may be a segment, a 
directory, or a link. If the entry is a segment, the contents of the segment are 
truncated first If the entry specifies a directory that contains entries, the code 
error_table_$fulldir is returned and hcs_$del_dir_tree must be called to remove the 
contents of the directory. Generally, programmers should use the delete_ subroutine 
rather than this entry point in order to ensure that their address space is properly 
cleaned up. 

USAGE 

declare hcs_$delentry_f i le entry (char (*) , char (*) , fixed bin (35)); 

call hcs_$del entry_f i 1 e (dir_name, entryname, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment, directory, or link. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

The hcs_$delentry_seg entry point performs the same function on a segment, given a 
pointer to the segment instead of the pathname. 

The user must have modify permission on the containing directory. If the entryname 
argument specifies a segment or directory (but not a link), the safety switch of the 
entry must be off. 
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hcs_$initiate 



Name: hcs_$delentry_seg 

The hcs_$delentry_seg entry point, given a pointer to a segment, deletes the 
corresponding entry from its containing directory. The contents of the segment are 
truncated first Generally, programmers should use the delete_ subroutine rather than 
this entry point in order to ensure that their address space is properly cleaned up. 

USAGE 

declare hcs_$delentry_seg entry (ptr, fixed bin(35))»- 
call hcs_$delentry_seg (seg_ptr, code); 
ARGUMENTS 
seg_ptr 

is the pointer to the segment to be deleted. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

The hcs_$delentry_file entry point performs the same function, given the pathname of 
the segment instead of the pointer. 

The user must have modify permission on the containing directory. The safety switch 
of the segment must be off. 



Name: hcs (initiate 

This entry point, when given a pathname and a reference name, makes known the 
segment defined by the pathname, initiates the given reference name, and increments 
the count of initiated reference names for the segment. 

Use of the initiate_file_ subroutine is preferred if a null reference name is desired. 
USAGE 

declare hcs_$ini tiate entry (char (*) , char (*) , char (*) , fixed bin(l), 
fixed bin (2), ptr, fixed bin (35)); 

call hcs__$ i ni t i ate (di r_name, entryname, ref_name, seg_sw, copy_ctl_sw, 
seg_ptr, code) ; 
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ARGUMENTS 
dir_name 

is the pathname of the containing directory. (Input) 
en try name 

is the entry name of the segment (Input) 
ref_name 

is the reference name. (Input) If it is zero length, the segment is initiated with a 
null reference name. 

seg_sw 

is the reserved segment switch. (Input) 

0 if no segment number has been reserved. 

1 if a segment number was reserved. 

copy_ctl_sw 

is obsolete, and should be set to zero. (Input) 
seg_ptr 

is a pointer to the segment. 
1 is seg_sw is on. (Input) 
0 is seg_sw is off. (Output) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have nonnull access on the segment (the en try name argument) in order 
to make it known. 

If a segment is concurrently initiated more than a system-defined number of times, 
the usage count of the segment is said to be in an overflowed condition, and further 
initiations do not affect the usage count. This affects the use of the hcs_$terminate_noname 
and hcs_$terminate_name entry points. If the reserved segment switch is on, then the 
segment pointer is input and the segment is made known with that segment number. 
In this case, the user supplies the initial segment number. If the reserved segment 
switch is off, a segment number is assigned and returned as a pointer. 

If entryname cannot be made known, a null pointer is returned for seg_ptr and the 
returned value of code indicates the reason for failure. Thus, the usual way to test 
whether the call was successful is to check the pointer, not the code, since the code 
may be nonzero even if the segment was successfully initiated. If entryname is already 
known to the user's process, code is returned as error_table_$segknown and the 
seg_ptr argument contains a nonnull pointer to entryname. If ref_name has already 
been initiated in the current ring, the code is returned as error_tab!e_$narnedup. The 
seg_ptr argument contains a valid pointer to the segment being initiated. If entryname 
is not already known, and no problems are encountered, seg_ptr contains a valid 
pointer and code is 0. 
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Name: hcs Sinitiate count 

The hcs_$initiate_count entry point, when given a pathname and a reference name, 
causes the segment defined by the pathname to be made known and the given 
reference name initiated. A segment number is assigned and returned as a pointer and 
the bit count of the segment is returned. Use of the initiate_file_ subroutine is 
preferred if a null reference name is desired. 

USAGE 

declare hcs_$ i ni tj ate_count entry (char (*) , char (*) , char (*) , 
fixed bin (24), fixed bin (2), ptr, fixed bin (35)); 

call hcs_$ i ni t i ate_count (dir_name, entryname, ref_name, bit_count, 
copy_ctl_sw, seg_ptr, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entry name of the segment (Input) 
ref_name 

is the reference name. (Input) If it is zero length, the segment is initiated with a 
null reference name. 

bit_count 

is the bit count of the segment. (Output) 
copy_ctl_sw 

is obsolete, and should be set to zero. (Input) 
seg_ptr 

is a pointer to the segment. (Output) 

code 

is a storage system status code. (Output) 
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NOTES 

The user must have nonnull access on the segment (the entryname argument) in order 
to make it known. 

If entryname cannot be made known, a null pointer is returned for seg_ptr and the 
returned value of code indicates the reason for failure. Thus, the usual way to test 
whether the call was successful is to check the pointer, not the code, since the code 
may be nonzero even if the segment was successfully initiated. If entryname is already 
known to the user's process, code is returned as error_table_$segknown and the 
seg_ptr argument contains a nonnull pointer to entryname. If entryname is not already 
known, and no problems are encountered, seg_ptr contains a valid pointer and code is 
0. If ref_name has already been initiated in the current ring, the code is returned as 
error_table_$namedup. The seg_ptr argument contains a valid pointer to the segment 
being initiated. If the seg_ptr argument contains a nonnull pointer, the bit_count 
argument is set to the bit count of the segment to which seg_ptr points. 



Name: hcs $set_bc seg 

This entry point, given a pointer to the segment, sets the bit count of a segment in 
the storage system. It also sets the bit count author of that segment to be the user 
who called it. 

The terminate_file_ subroutine performs this same function and its usage is 
recommended. 

USAGE 

declare hcs_$set_bc_seg entry (ptr, fixed bin(2*0, fixed bin (35)); 

call hcs_$set_bc_seg (seg_ptr, bit_count, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment whose bit count is to be changed. (Input) 
bit_count 

is the new bit count of the segment (Input) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have write access on the segment, but does not need modify permission 
on the containing directory. 
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The hcs_$set_bc entry point performs the same function, when provided with a 
pathname of a segment rather than a pointer. 



Name: hcs $terminate file 

This entry point, given the pathname of a segment, terminates all the reference names 
of that segment and then removes the segment from the address space of the process 
(makes the segment unknown). 

The term_ subroutine performs the same operation as the hcs_$terminate_file entry 
point, but, in addition, causes links to the entry's linkage section to be unsnapped. 
Use of the term_ subroutine is recommended. 

USAGE 

declare hcs_$termi nate_f i 1 e entry (char (*) , char (*) , fixed bin(l), 
fixed bin (35)) ; 

call hcs_$termi nate_f i 1 e (dir_name, entryname, seg_sw, code); 

ARGUMENTS 

dir_name 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment. (Input) 
seg_sw 

is the reserved segment switch. (Input) 

1 saves segment number in the reserved segment list. 

0 does not save segment number. 

code 

is a storage system status code. (Output) 
NOTES 

The hcs_$terminate_seg entry point performs the same operation given a pointer to a 
segment instead of a pathname; the hcs_$terminate_name and hcs_$terminate_noname 
entry points terminate a single reference name. 

The reference names that are removed are those for which the ring level associated 
with the name is greater than or equal to the validation level of the process. If any 
reference names exist that are associated with a ring level less than the validation level 
of the process, the segment is not made unknown and the code is returned as 
error_table_$bad_ring_brackets. For a discussion of rings, refer to the Programmer's 
Reference Manual. 
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Name: hcs__$terminate name 

This entry point terminates one reference name from a segment and decrements a 
count of initiated reference names for the segment. 

The term_$single_refname entry point performs the same operation as the 
hcs_$terminate_name entry point, unsnapping links as well. Use of the term_ 
subroutine is recommended. 

USAGE 

declare hcs_$termi nate_name entry (char (*) , fixed bin (35)); 

call hcs_$termi nate_name (ref_name, code); 

ARGUMENTS 

ref_name 

is the reference name to be terminated. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

If a segment is concurrently initiated more than a system-defined number of times, 
the usage count of the segment is said to be in an overflowed condition. Under such 
circumstances, the hcs_$terminate_name entry point does not reduce the usage count, 
but leaves the segment in the overflowed state. To terminate the segment, 
hcs_$terminate_file or hcs_$terminate_seg should be used. 

If the hcs_$terminate_name entry point reduces the count of initiated reference names 
for that segment to zero, the segment is removed from the address space of the 
process (made unknown). 

The hcs_$terminate_noname entry point terminates a null reference name from a 
specified segment; the hcs_$terminate_file and hcs_$terminate_seg entry points terminate 
all reference names of a segment and make the segment unknown, given its pathname 
or segment number, respectively. 
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Name: hcs_$terminate noname 

This entry point terminates a null reference name from the specified segment and 
decrements a count of initiated reference names for the segment 

The terminate_file_ subroutine performs this same function and its usage is 
recommended. 

USAGE 

declare hcs_$termi nate_noname entry (ptr, fixed bin (35)); 
call hcs_$termi nate_noname (seg_ptr, code); 
ARGUMENTS 
seg_ptr 

is a pointer to the segment. (Input/Output) 

code 

is a storage system status code. (Output) 
NOTES 

If a segment is concurrently initiated more than a system-defined number of times, 
the usage count of the segment is said to be in an overflowed condition. Under such 
circumstances, the hcs_$terminate_noname entry point does not reduce the usage count, 
but leaves the segment in the overflowed state. To terminate the segment, 
hcs_$terminate_file or hcs_$terminate_seg should be used. 

If the hcs_$terminate_noname entry point reduces the count of initiated reference 
names of the segment to zero, the segment is removed from the address space of the 
process (made unknown). This entry point is used to clean up after making a segment 
known and initiating a single null reference name; see also the hcs_$initiate, 
hcs_$initiate_count, and hcs_$make_seg entry points. 

The hcs_$terminate_name entry point terminates a specified nonnull reference name; 
hcs_$terminate_file and hcs_$terminate_seg entry points terminate all reference names 
of a segment and make the segment unknown, given its pathname or segment number, 
respectively. 
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Name: hcs $terminate seg 

This entry point, given a pointer to a segment in the current process, terminates all 
the reference names of that segment and then removes the segment from the address 
space of the process (makes it unknown). 

The term_$seg_ptr entry point performs the same operation as the hcs_$terminate_seg 
entry point, unsnapping links as well. Use of the term_ subroutine is recommended. 

• USAGE 

declare hcs_$termi nate_seg entry (ptr, fixed bin(l), fixed bin (35)); 

call hcs_$ termi nate_seg (seg_ptr, seg_sw, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment to be terminated. (Input) 
seg_sw 

is the reserved segment switch. (Input) 

1 saves segment number in reserved segment list. 

0 does not save segment number. 

code 

is a storage system status code. (Output) 
NOTES 

The hcs_$terminate_file entry point performs tne same operation given the pathname 
of a segment instead of a pointer; the hcs_$terminate_name and hcs_$terminate_noname 
entry points terminate a single reference name. 

The only reference names that are removed are those for which the ring level 
associated with the name is greater than or equal to the validation level of the 
process. If any reference names exist that are associated with a ring level less than 
the validation level of the process, the segment is not made unknown and the code is 
returned as error_table_$bad_ring_brackets. For a discussion of rings refer to the 
Programmer's Reference Manual. 
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Name: hcs Struncate seg 

This entry point, given a pointer, truncates a segment to a specified length. If the 
segment is already shorter than the specified length, no truncation is done. The effect 
of truncating a segment is to store zeros in the words beyond the specified length. 

The terminate_file_ subroutine performs this same operation, and its usage is 
recommended. 

USAGE 

declare hcs_$truncate_seg entry (ptr, fixed bi n (19) » fixed bin(35))» 

call hcs_$truncate_seg (seg_ptr, length, code); 

ARGUMENTS 

seg_ptr 

is a pointer to the segment to be truncated. (Input) Only the segment number 
portion of the pointer is used. 

length 

is the new length of the segment in words. (Input) 

code 

is a storage system status code. (Output) 
NOTES 

The user must have write access on the segment in order to truncate it 
A directory cannot be truncated. 

A segment is truncated as follows: all full pages after the page containing the last 
word of the new length (as defined by the length argument) segment are discarded. 
The remainder of the page containing the last word is converted to zeros. 

Bit count is not automatically set by the hcs_$truncate_seg entry point If desired, bit 
count may be set by using the hcs_$set_bc_seg entry point 

The hcs_$truncate_file entry point performs the same function when given the 
pathname of the segment instead of the pointer. 
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ipc_$decl_event_call_chn 



Name: ipc $create_ev_chn 

This entry point creates an event-wait channel in the current ring. 
USAGE 

declare i pc_$create_ev_chn entry (fixed bin (71), fixed bin (35)) J 

call i pc__$create_evj:hn (channeled, code); 

ARGUMENTS 

channeled 

is the identifier of the event channel. (Output) 

code 

is a standard status code. (Output) 



Name? ipc Sdecl event call cho 

This entry point changes an event-wait channel into an event-call channel. 
USAGE 

declare i pc_$dec l__event_cal l_chn entry (fixed bin(7D> entry, ptr, 
fixed bin, fixed bin (35))! 

call i pc_$decl_event_cal l_chn (channel_id, cal l_chn__procedure, data__ptr, 
pr i or i ty, code) ; 

ARGUMENTS 

channeled 

is the identifier of the event channel. (Input) 
call_chn_procedure 

is the procedure entry point invoked when an event occurs on the specified 
channel. (Input) 

data_ptr 

is a pointer to a region where data to be passed to and interpreted by that 
procedure entry point is placed. (Input) 
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link_unsnap_ 



priority 

is a number indicating the priority of this event-call channel as compared to 
other event-call channels declared by this process for this ring. If, upon 
interrogating all the appropriate event-call channels, more than one is found to 
have received an event, the lowest-numbered priority is honored first, and so on. 
(Input) 

code 

is a standard status, code. (Output) 



Name: link_ unsnap__ 

The link_unsnap_ subroutine restores snapped links pointing to a given segment or its 
linkage section. Such links then appear as if they had never been snapped (changed 
into ITS pairs). This is accomplished by sequentially indexing through the Linkage 
Offset Table (LOT) and for each linkage section listed there by searching for links to 
be restored. 

USAGE 

declare link unsnap entry (ptr, ptr, ptr, fixed b i n (1 7) » fixed 
bin(17f); 

call 1 i nk__unsnap_ (lot__ptr, isot_ptr, linkage_ptr, hcsc, high_seg); 

ARGUMENTS 

lot_ptr 

is a pointer to the LOT. (Input) 
isot_ptr 

is a printer to the ISQT. (Input) 
linkage_ptr 

is a pointer to the linkage section to be discarded. (Input) 

hscs 

is one less than the segment number of the first segment that can be unsnapped. 
(Input) 

high_seg 

is the number of LOT slots used in searching for links to be restored. (Input) 
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multi segment file (MSF) ACL 
msf manager $acl add 
" 2-615 " 



i-1 



AG93-05A 



access control (cont) 

mul ti segment file (MSF) ACL 
msf_manager_$acl_del ete 

2-617 ~ 
msf_manager_$acl_l ist 

2-618 ~ 
msf_manager_$ac1_repl ace 

2-619 

mul ti segment file ACL 

copy_acl_ 2-126 
pr ivi leges 

get_pr ivi leges_ 2-370 
rings 

get_ring_ 2-373 

hcs_$get_d i r_r i ng_brackets 
2-417 

hcs_$get_r i ng_brackets 

" 2-^27 
hcs_$get_r i ng_brackets_seg 
2-427 

hcs $set_d i r_r i ng_brackets 
2-461 

hcs_$set_r i ng__brackets 

segment ACL 

copy_acl__ 2-126 
hcs_$add_acl_entr i es 

~ 2-384 
hcs_$add_i nac l_entr i es 
2-390 

hcs_$delete_ad_entr i es 
2-403 

hcs_$delete_i nacl_entr ies 
2-406 

hcs_$f s_get_mode 2-409 
hcs_$get_access_c 1 ass 

~ 2-414 
hcs_$get_access_c 1 ass_seg 

* 2-415 
hcs_$l ist_acl 2-442 
hcs_$ 1 i st_i nacl 2-446 
hcs_$replace_acl 2-453 
hcs_$repl ace_i nacl 2-457 
validation level 

cu_$level_get 2-154 
cu~$level~set 2-154 



access isolation mechanism 
(AIM) 
aim_check_ 2-13 
compute_common_a i m_ce i 1 i ng_ 
2-100 

display_access_class_ 2-229 
get_pr i vi 1 eges_ 2-370 
get_process_access_c 1 ass__ 
2-371 

get_system_aim_attr ibutes_ 
2-374 

read_al lowed_ 2-668.10 
read_wr i te_a 1 1 owed_ 2-670 
send__mai l_$access_cl ass 
"2-723 

send_mai l_$path_access_class 
2-724 

system info $access ceiling 

2-842 ~ 
system_i nfo_$category names 

2-842 ~ 
system_info $ level names 

2-845 ~~ 

account i ng 

resource usage 

cpu__t ime_and paging 
~~ 2-130 
shift definition table 
system_i nf o_$shi f t_tab1e 

2-849 
storage quota 

hcs_$quota_move 2-450.1 
hcs_$quota_read 2-451 
usage information 

system_i nf o_$abs_pr i ces 

2-841 ~ 
system_i nf o_$devi ce_pr i ces 

2-843 

system_i nfo_$ io_pr i ces 
2-844 

system_info_$pr ices 2-847 
system_i nf o_$resource_pr i ce 
2-847 

active functions 

ac t i ve_f nc_er r_$ suppr es s_name 
2-9 
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active functions (cont) 
argument processing 

cu_$af_arg_count 2-138 
cu $af_arg count rel 

2-139" 
cu_$af_arg_ptr 2-140 
cu_$af_arg_ptr_rel 2- HI 
cu_$af_return_arg 2-11*2 
cu $af return_arg_rel 

2-143 
error messages 

active_f nc_err_ 2-7 

active strings 

cu_$evaluate active string 
2-150 

cu_$get_evaluate_active str 
2-152.2 

cu $reset evaluate active_str 

~ 2-157 
cu $set evaluate active str 

2-T58 

active fnc err subroutine 
2-7 

active fnc err $suppress name 
2-9 

address 

runtime_symbol_info_$address 
2-700 

address space 

making segment addressable 
hcs_$ initiate 2-1+37, A- 11 
hcs $ initiate count 2-1+39, 
A-13 

ini tiate_f i le__ 2-5 10 
i n i t i ate_f i 1 e_$component 
2-511 
making segment 

nonaddressabl e 
hcs_$terminate_f i le A- 16 
hcs_$termi nate_name A- 17 
hcs_$termi nate_noname 

~ A-18 
hcs_$termi nate_seg A- 19 
term__$ref name 2-853 



address space (cont) 
making segment 

nonaddressabl e 
term_$seg_ptr 2-854 
term_$s ingle refname 

2-854 
term_$unsnap 2-855 

add_bi t_of f set subroutine 
- 2-9 

add char offset subroutine 
~ 2-10 

add_epi logue_handl er_ 
subroutine 2-11 

adjust bit count subroutine 
2-12 ~ 



see access isolation mechanism 

aim_check_ subroutine 2-13 

aim_check_$equal 2-13 

a im_check_$ greater 2-13 

aim_check_$greater_or_equal 
2-14 

a im_check_$ i n_range 2-14 

aiinjjti 1_ subrout i ne 2-15 

aim_uti l_$get_access_dass 
2-15 

aim_uti l_$get_categor ies 2-16 

aim_uti l_$get_1evel 2-16 

aim_uti l_$get_pr ivi leges 2-15 

a i m_ut i 1 $make_access_c 1 ass 
2-17 
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anonymous users 

ge t_g r oup_ i d_ 2-366 
get__group_id_$tag_star 
2-367 

ansi_tape_io_ I/O module 3~3 

answering service 
dial f aci 1 i ty 

conver t_d i a 1 _message_ 
2-120 

dial_manager_ 2-220 

archive component 

arch i ve_$get_component_i nfo 
2-19 

archive_$next_component_i nfo 
2-23 

expa nd_j>a t h name_$ componen t_a 

2-21*8 
i n i t i at i ng 

i n i t i ate_f i 1 e_$ component 
2-511 

na t hnamo 

I — — — 

expand_pathname_$component 
2-21*7 

get_equal__name_$component 

~ 2-363 
pathname_$component 2-643 
pathname_$component_check 

2~$kk 
ref erenc i ng 

arch i ve__$get_component 
2-17 

archive_$l i st_components 
2-21 

arch i ve_$next_component 
2-22 

archive_ subroutine 2-17 

archi ve_$get_component 2-18 

arch i ve_$get__component__i nfo 
2 -! 9 

arch i ve_$ 1 i st_components 2-21 
archi ve_$next_component 2-22 



archi ve_$ nex t_componen t_ info 
2-23 

area management 
cl eanup 

release_area_ 2-671 
i nformat ion 

area_info__ 2-25 
ini tial ization 

def i ne_area_ 2-215 
subsystem environment 

ssu_$get_area 2-775 

ssu_$release_area 2-796 
system free area 

get_system_f ree_area_ 
2-376 

area_info_ subroutine 2-25 

area_i nf o_$get_block_data_i nfo 
2-30 

argument descriptors 

decode descriptor 2-2 Ik 
get_entry_arg_descs_ 2-354 
get_entry_poi nt_dcl_ 2-359 

argument 1 i st 
manipulating 

get_entry_arg_descs 2-355 
terminal input 

cu_$generate_cal 1 2-151 

argument processing 
active functions 

cu__$af_arg_count 2-138 
cu_$af_arg_count rel 
2-139 

cu_$af_arg_ptr 2-11*0 
cu_$af_arg__ptr_rel 2-11*1 
cu_$af_return_arg 2-11*2 
cu_$af__return arg_rel 
2-11*3 
commands 

cu_$arg_count 2-11*3 
cu_$arg_count_rel 2-11*1* 
cu_$arg_l i st_ptr 2-11*5 
cu_$arg_ptr 2-11*5 
cu_$arg_ptr_rel 2-11*6 
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argument processing (cont) 
subsystem 

ssu_$arg_count 2-766 
ssu_$return_arg 2-798 

ar i thmet i c_to_asc i i_ 
subroutine 2-31 

array 

runtime information 

runtime symbol info $array 
2-702 

runtime symbol info_$array_d 
""2-701* " 

ASCI I 

character conversion 

asci i_to_ebcdic_ 2-32.1 
ebcd i c_to_asc i i _ 2-21*3 

translation table 

ascii to_ebcdic_$ae table 
2-32.2 

ebcdic__to ascii $ae table 
2-21*1*" 

ASCII files 
transf err i ng 

ibm_pc_io_ 3 "51 

ASCII text 

parse_file_ 2-61*2.7 

asei i_to_bcd__ subrout i ne 2-32 

ascii to__ebcdic_ subroutine 
2-32.1 

ask_ subroutine 2-37 

ask_$ask_c 2-38 

ask_$ask__cf lo 2-39 

ask_$ask_cint 2-38 

ask_$ask_cl i ne 2-39 

ask_$ask_clr 2-1*0 



ask_$ask_cnf 2-1*0 

ask_$ask_cyn 2-1*0 

ask_$ask_flo 2-1*2 

ask_$ask_int 2-1*1 

ask_$ask_l ine 2-1*2 

ask_$ask_n 2-1*3 

ask_$ask_nf 2-1*3 

ask_$ask_nf lo 2-1*1* 

ask_$ask_nint 2-1*1* 

ask_$ask_nl i ne 2-1*5 

ask_$ask_nnf 2-1*5 

ask__$ask_nyn 2-1*6 

ask_$ask_prompt 2-1*6 

ask_$ask_set1 ine 2*1*7 

ask_$ask_yn 2-1*7 

assign^ subroutine 2-1*8 

ass i gn_$ass i gn_round_ 2-50 

assign_$assign_truncate_ 2-50 

assign_$computational_ 2-1*9 

asterisks 

see star convention 

asynchronous programs 
ipc_ 2-565 

audits 1/0 module 3"23 

author 

hcs_$get__author 2-1*16.1* 
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auto cal 1 channel 

convert_d i al_message_ 2-120 
dial _manager_$d i a 1_out 
2-222 

automatic storage 
runtime information 
runt ime__symbol__i nf o_ 
2-699 



B 



bcd_to_asci i_ subroutine 2-50 

bef ore_journal_manager_ 
subroutine 2-51 

bef ore_j our na l_manager_$c 1 ose_b 
2-51 

bef ore_journal_manager_$create 
2-52 

bef ore_journal_manager_$get_bj 
2-53 

bef ore_journal manager_$get_d_b 
2-53 

bef ore_Journal_manager_$open_bj 
2-54 

before _j ournal_manager_$set_d_b 
2-55 

bef ore_Journal_manager_$set_tr 
2-56 

bi nder 
data 

object_i nfo_$1ong 2-631 
bisync_ I/O module 3"27 



bit count 

archive component 

arch i ve_$get_component 
2-17 

arch i ve_$next_component 
2-22 

author 

hcs_$get_bc_author 2-4 17 
obta i n i ng 

hcs_$ini tiate_count 2-439* 
A-13 

hcs_$statusjni ns 2-489 
sett i ng 

adjust_bi t_count_ 2-12 
hcs_$set_bc 2-460 
hcs__$set_bc_seg A- 12* 

bit offset 

add_bi t_offset_ 2-9 
bit_offset_ 2-57 
set_bi t_of fset_ 2-730 

bit strings 
access modes 

cv_d i r_mode_ 2 - 1 65 

cv_mode_ 2-172 
formatt i ng 

ioa_ 2-518 
sort i ng 

sort__i tems_$bi t 2-742.1 

sort_i tems_i ndi rect_$bi t 
™ 2-745 

bit_offset_ subroutine 2-57 

bound segment 
information 

component__i nf o_ 2-96 
get_bound_seg_i nf o_ 2-351 

break characters 
lex_string_ 2-569 
parse_file_ 2-642.7 

bulk I/O 
off 1 i ne 

dprint_ 2-233 
iod_info_ 2-529 



i-6 



AG93-05A 



bulk I/O (cont) 
of f 1 ine 

system info $io prices 
2-844 " 

bulk store 

hcs_$force_wr i te 2- 40 7 



C 



cal ler 

entry point bound 
hcs $set entry bound 
2-1*63, 2-462.1 

card punch 
I/O daemon 

dprint_ 2-233 
remote device 

remote_punch_ 3*144 

cbjnenu_ subroutine 2-57 

cbjnenu_$create 2-57 

cb_menu_$delete 2-60 

cbjnenu_$descr ibe 2-60 

cbjnenu_$destroy 2-61 

cb_menu_$di splay 2-62 

cbjnenu_$get_choice 2-63 

cb_menu_$ i n i t 1 2-64 

cb_menu_$ i n i t2 2-64 

cb_menu__$ list 2-65 

cb_menu__$retr i eve 2-67 

cbjnenu_$ store 2-67 

cb_menu_$termi nate 2-68 



cb__wi ndow_ subroutine 2-69 

cb_wi ndow__$ change 2-69 

cb_wi ndow_$clear_wi ndow 2-70 

cb_wi ndow_$ create 2- 71 

cb_wi ndow_$destroy 2-71 

change_def aul t_wdi r_ 
subroutine 2-83 

change_wdir_ subroutine 2-84 

character offset 

add_char_of f set_ 2-10 
char_offset_ 2-84 
set_char_of f set_ 2-730 

character string 
conversion 

ascii to_ebcdic_ 2-32.1 

ask_ ~2-37 

assign^ 2-48 

char_to_numer ic_ 2-85 

ebcd i c_to_asc i i_ 2-243 
formatti ng 

ioa_ 2-5 18 
mode strings 

mode_string_ 2-607 
parsing 

1 ex_str i ng_ 2-569 
quoting 

requote_str ing_ 2-675 
sorti ng 

sort items $varying char 
~2-742?5 

sort i tems_indi rect $char 
2-746 

sort items i ndi rect_$adj char 
~2-744" 

sort_i terns i ndi rect_$var_char 

2-749 
translations 
mvt_ 2-624 

char_offset subroutine 2-84 
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char_to_numer i c_ subroutine 
2-85 

check_gate_access_ subroutine 
2-85 

check_star_name_ subroutine 
2-87 

check_star_name_$entry 2-88-3 

check_star_name_$path 2-88 « 4 

cleanup 

address space 

hcs_$termi nate_f i le A- 16 
hcs_$termi nate_name A- 1 7 
hcs_$termi nate_noname 

~ A- 18 
hcs_$termi nate_seg A- 19 
term_ 2-853 
area 

rel ease__area_ 2-671 
hit count 

adjust_bi t_count_ 2-12 
I/O 

iox_$c1ose 2-535 

iox__$detach_iocb 2-538 
mul ti segment files (MSFs) 

msf_manager_$adjust 2-620 
process 

add_epi logue_handler_ 
~ 2-11 

execute_epi Iogue_ 2-245 
run units 

add_epilogue handler_ 
2-11 

execute_epi logue_ 2-21*5 
run_$envi ronment_i nf o_ 
~ 2-698 
temporary segment 

rel ease_temp_segments_ 
2-673 

rei ease_temp_segment_ 
2-672 

clock reading 
clock_ 2-88.4 
datebin_ 2-208 



clock reading (cont) 

decode_clock_value_ A-2 
decode_clock value_$date__time 
A-3 

clock = subroutine 2-88*4 
COBOL 

data type conversion 
ass i gn__$computat i ona 1_ 

2-49 
error messages 

pr i nt_cobol_error_ 2-650 
pr i nt_cobol_error_$swi tch 
2-650 
symbol information 
runt ime_symbol_i nf o_ 
2-699 

command language 
expans i on 
abbrev_ 2-3 



active string evaluation 
cu_$eval uate_act i ve_str i ng 
2-150 

cu_$get_eval__act_str i ng 

2-152.2 
cu__$reset_eval_act_str i ng 

2-157 

cu_$set__eval_act_str i ng 
2-158 " 

argument processing 
cu__$arg_count 2-143 
cu_$arg_count_rel 2-144 
cu__$arg_l i st_ptr 2-145 
cu_$arg_ptr 2-145 
cu_$arg_ptr_rel 2-146 
cu_$generate_cal 1 2-151 

asking questions 

command_query_ 2-9 1 
command_query_$yes_no 
2-95 

command processor escape 
cu_$cp 2-148 
cu__$get_command_name 
2-T51 
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command uti 1 i ty programs 
(cont) 

command processor escape 
cu $get comma nd_name_r el 
2-T52 

cu_$get_command_processor 

2-152.1 
cu_$ reset command proc 

2-156 

cu_$set command_processor 
2-T58 

command query $set cp esc e 

2-91+ 
entry value 

cu $decode entry value 

cu_$make entry_value 

2-155 
error handlers 
cu_$cl 2-11*7 
cu $get__cl_i ntermed i ary 

2-151 

cu $reset cl intermediary 

cu $set cl intermediary 

2-T57" 
error messages 
com_err_ 2-89 
com err_$suppress name 
~ 2-90 
mode strings 

mode_string_ 2-607 
pointer to cal ler 

cu_$cal ler_ptr 2-147 
ready state 
cu $get ready_mode 

2-T52.2 
cu_$get ready procedure 
2-T53 

cu_$ready_proc 2-155 
cu $reset ready procedure 
2-157 

cu_$set_readyjnode 2-159 
cu__$set_ready_procedure 



-> _ 1 rn 



r ing val idation level 
cu_$level_get 2- 154 
cu_$level_set 2-154 



command utility programs 
(cont) 
stack uti 1 i ty 

cu_$grow_stack frame 
2-153 

cu_$shr i nk_stack__f rame 
2-160 

cu_$stack_f rame__ptr 2-160 
c u_$ s t a c k_f r ame_s i z e 
2-160 
system free storage 
get system free_area 
~ 2-376~ 

command_query_ subroutine 
2-91 

command query $set_cp_esc_enable 
2-94 

command_query_$yes_no 2-95 

communication 

i nterprocess 
i Pc_ 2-556 

interuser 
send_mail_ 2-722.1 
send_mai l_$path 2-724 

communications channels 
bisync 3-27 
ibm2780 3"74 
ibm3270l 3-77 
5bm3780_ 3-86 
remote_i nput_ 3" 136 
remote_pr i nter_ 3" 138 
remote_punch_ 3" 144 
remote_telepr inter_ 3- 146 

compar i son 
star names 

check_star_name_ 2-87 
hcs_$star_~ 2-471 
hcs_$star_di r__l i st_ 2-474 
hcs_$star_l i st 2-479 
match_star_name_ 2-583 

component info_ subroutine 
2-96~ 
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component_i nf o_$name 2-97 

component^ nf o_$of f set 2-97 

compute_common_airn_cei 1 i ng_ 
subroutine 2-100 

com_err_ subroutine 2-89 

com_err_$suppress_name 2-90 

condi t ion hand 1 i ng 
disconnected process 

sus_s i gnal_handl er_ 2-837 
exponent control 

hcs_$get_exponent_control 
2-418 

hcs_$set_exponent_control 
2-464 

exponent_control_$f aul t_ov 
2-249 

exponent_control_$f aul t__un 

cxponen t_con t r o 1 _$ r ss tar t__ov 
2-21*9 

exponent_control__$restart_un 

2-249 
machine conditions 

prepare_mc_restart_ 2-647 
s i gnal 1 i ng 

cont i nue_to_signal_ 2-102 

signal__ 2-741 
signal_io_ 3~147 
static handlers 

sct_manager_ 2-712 

condi tions 

asking questions 
ask_ 2-37 

comma nd__query_ 2-91 
command_query_$yes_no 
2-95 

c omma nd__q u e r y_$ s e t_c p_e s c_e 

2-94 
error messages 

acti ve_f nc_err_ 2-7 



conditions (cont) 
error messages 

act i ve__f nc__err_$suppress_name 
2-9 

com_err_ 2-89 
com_err_$suppress_name 
2-90 

cond i t i on_i nterpreter 

2-101 
sub_err_ 2-830 
information 
f ind_condi tion info 

2-285 
s i gnal i ng 

signal_io_ 3 - 147 
stack history 

f i nd_cond i t i on_f r ame_ 
2-284 

condi tion_ subroutine 2-100.1 

cond i t i on_i nterpreter_ 
subroutine 2-101 

cont i nue_to__s i gnal subroutine 

2-102 
conversion 
access class 

convert_access_class 
2-104 

di splay_access_class_ 
2-229 
addresses 

cv_entry_ 2-166 

cv_ptr_ 2-174 

cv_ptr_$termi nate 2-174 
character string 

asci i _to_ebcd i c__ 2-32.1 

ebcdic_to__asci i_ 2-243 
data types 

assign_ 2-48 

ass i gn_round_ 2~50 

ass i gn_truncate_ 2-50 
date and time 

clock_ 2-88.4 

datebin_ 2-208 

decode_clock__value__ A-2 

encode_clock_value__ A-5 
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conversion (cont) 

decode__clock value_$date__time 
A-3 

encode_c 1 ock__va 1 ue_$of f sets 
A-6 

event messages 

converted ial message_ 
2-120 
formatted output 

ioa_ 2-518 
locator 

stu $offset to pointer 
" 2-821* " 

stu $poi nter_to_of f set 
~ 2-825 
numer i c 

ask_ 2-37 

cv_bin_ 2-161 
numeric to string 

ar i thmet i c__to__asc i i_ 2-31 

ass i gn_ 2-1+8 

ass ign_round_ 2-50 

assign_truncate_ 2-50 

cv_bin_ 2-161 

cv_bin_$dec 2-161 

cv_bin_$oct 2-162 

numer i c_to_asci i_ 2-627 

numeric to ascii_base_ 

2-628"" 
status code 

convert status_code_ 
2-T23 

cv_error_$name 2-168 

str i ng 

ask_ 2-37 

string to numeric 
assign^ 2-1*8 
ass i gn_round_ 2-50 
assign__truncate_ 2-50 
char_to_numer ic_ 2-85 
cv_dec_ 2-162 
cv__dec_check_ 2-163 
cv~f 1 oat 2-168 
cv_f loat_double 2-169 
cv_hex_ 2-171 
cv_hex_check_ 2-171 
cv_oct_ 2-173 
cv_oct_check_ 2-173 



conversion (cont) 
User__id 

cv_userid_ 2-182 

conver t_access_aud i t_f 1 ags_ 
subroutine 2-103 

convert__access_audi t_f lags_$f_s 
2-103 

convert access audit flags $t s 
2-T03 

conver t_access__class_ 
subroutine 2-104 

conver t_access_c 1 ass_$decode 
2-101* 

conver t_access class_$encode 
2-105 

convert accessed ass $from_str 
2 r 105, 2-106 

conver t_access class $minimum 
2-107 

conver t_access cl ass_$to_str 
2-108 

conver t_access class_$to_str_r 
2-109, 2-110, 2-111 

conver t^date^toja i nary_ 
subroutine 2-111 

convert date to binary $rel 
2-Tl9 

conver t_di a l__message_ 
subroutine 2-120 

conver t_d i a l_message_$return_i o__m 
2-720 

conver t_s ta tus_code_ 
subroutine 2-T23 
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copy_ 2-122* 

copy_acl_ subroutine 2-126 

copy_dir_ subroutine 2-127 

CPU 
usage 

cpu_t i me_and_pag i ng_ 
2-130 

system_i nf o__$abs__pr i ces 
2-81+1 

system_i nfo_$pr i ces 2-847 

cpu__t i me_and_pag i ng_ 
subroutine 2-130 

create_data_segment_ 
subroutine 2-131 

create_i ps_mask_ subroutine 
2-135 



di rectory 

hcs_$append_branchx 2-393 
hcs_$create_branch__ 2-1*00 

entry value 

hcs__$make_entry 2-1*1*8 

1 i nk 

hcs__$append_l i nk 2-395 
reference name 

hcs__$ini tiate 2-Z*37 1 A-ll 
hcs_$ i ni tiate_count 2-1*39* 
A-13 

segment 

create_data_segment_ 

2-131 " 
hcs_$append_branch 2-392 
hcs_$append_branchx 2-393 
hcs_$create_branch_ 2-1*00 
hcs_$make_seg 2-1*50 

temporary segment 

get_temp_segments_ 2-377 
get_temp_segment_ 2-376 

cross_ring_ I/O module 3"32 

cross_r i ng_io_ 2-136 



cu_ subroutine 2-136 
cu_$af_arg_count 2-138 
cu_$af_arg_count_rel 2-139 
cu_$af_arg_ptr 2-11*0 
cu_$af_arg_ptr_re1 2-11*1 
cu_$af_return_arg 2-11*2 
cu_$af_return_arg_rel 2-11*3 
cu_$arg_count 2-11*3 
cu_$arg_count_rel 2-11*1* 
cu_$arg_l i st_ptr 2-11*5 
cu_$arg_ptr 2-11*5 
cu_$ a r g_p t r_r e 1 2-11*6 
cu_$cal ler_ptr 2-11*7 
cu_$cl 2-11*7 
cu_$cp 2-11*8 

cu_$decode__entry_value 2-11*9 

cu_$evaluate_act i ve_str i ng 
2-150 

cu_$generate_cal 1 2-151 

cu_$get_cl_i ntermedi ary 2-151 

cu_$get_command_name 2-151 

cu_$get__command_name_rel 
2-152 

cu $get command processor 
2-T52 . 1 

cu_$get_evaluate_act i ve string 
2-152.2 
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cu_$get_readyjnode 2-152.2 

cu_$get_readyj3rocedure 2-153 

cu_$grow_stack_f rame 2-153 

cu_$level_get 2-154 

cu_$1evel_set 2-154 

cu_$make_entry_value 2-155 

cu_$ready_proc 2-155 

cu_$reset cl intermediary 
2-156 

cu_$reset_command processor 
2-156 

cu $reset evaluate active_str 
2-157 

cu $reset ready procedure 
2-157 

cu__$set_cl_J ntermediary 2-157 

cu $set command processor 
2-T58 

cu $set_evaluate active_str ing 
2-158 

cu_$set_ready_mode 2-159 
cu_$set_ready_procedure 2-159 
cu_$shr I nk_staek_f rame 2-160 
cu_$stack_f rame_ptr 2-160 
cu_$stack_f rame_size 2-160 
cv_bin_ subroutine 2-161 
cv_bin_$dec 2-161 
cv bin_$oct 2-162 



cv_dec_ 2-162 

cv_dec check subroutine 
2 r 163 

cv_d I r_mode_ subroutine 2-165 

cv_entry_ subroutine 2-166 

cv__error_$name 2-168 

cv_float_ subroutine 2-168 

cv float double subroutine 
2-169 

cv_fstime_ subroutine 2-170 

cv_hex_ subroutine 2-171 

cv hex check subroutine 
2-171 

cvjnode_ subroutine 2-172 

cv_oct_ subroutine 2-173 

cv oct check subroutine 
2-173 

cv_ptr_ subroutine 2-174 

cv_ptr_$termi nate 2-174 

cv_rcp attributes subroutine 
2-176.1 

cv_rcp attr ibutes_$f rom_str i ng 
2-176.1 

cv rep attributes $f rom_str_rel 
2-177 

cv_rcp_attr i butes__$mod i f y 

2-1 7R 

fc - f w 

cv rep attributes_$modify rel 
2-178 
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cv_rcp_attr i butes_$protected__c 
2-179 

cv_rcp_attr i butes_$reduce__impl 
2-180 

cv_rcp_attr i butes_$test_va1 id 
2-180 

cv_rcp_attr i butes_$to_str i ng 
2-181 

cv userid subroutine 2-182 



D 



daemon 

see I/O daemon 

data 

argument descriptors 

decode descriptor 2— 211$ 
structures 

create_data_segment_ 
2-131 
transfer 

ibm_pc_io_ 3 "51 

xmodem_io_ 3~285 

data base 
hash table 
hash_ 2-379 
rehash_ 2-671 

data items 
sort i ng 

sort_i tems_$general 
2-742.3 

sort_i tems_i nd i rect_$general 
2-748 

data transfer protocol 
ibm_pc_io_ 3"51 
xmodem_jo_ 3-285 



date and time 
conversion 

clock_ 2-88*4 
datebin_ 2-208 
decode_clock__value_ A-2 

encode = clock_val ue = A-5 
decode_c 1 ock_va 1 ue_$da te_t i me 
A-3 

encode_c 1 ock_va 1 ue__$of f sets 
A-6 

datebin_ 2-208 

date_time_ subroutine 2-182 

date_t ime_$date_time_ 2-183 

date_t ime_$f ormat 2-184 

date_t i me_$f ormat_max_l ength 
2-195 

date_t ime_$f rom_clock 2-196 

date_t ime_$f rom__clock_i nterval 
2-199 

date_t ime_$f st ime 2-202 

da te_t i me_$of f set_to_c 1 ock 
2-203 

date_time_$set_lang 2-205 

date__t ime__$set__zone 2-205 

date_t ime_$to_clock 2-206 

da te_t ime_$val id_f ormat 2-207 

debuggi ng 

act i ve_f nc_err_$suppress_name 

2-9 " 
condi tions 

continue_to_signal_ 2-102 
error messages 

act i ve_f nc_err_ 2-7 

com_err_ 2-89 
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debugging (cont) 
error messages 

com err $suppress__name 
2-90 

condition interpreter 

2-10T 

convert status code 
2-T23 
inspecting segments 

dump_segment__ 2-21*0 
stack trace 

f ind_condi tion_f rame 
2-281* 

f i nd_cond i t i on_i nf o_ 
"2-285 

stu $get impl ici t_qual if ier 

~ 2-8T5 
subsystems 

ssu_$get_debug_mode 2-777 
ssu_$set_debugjnode 2-799 
sweep_disk_$loud 2-81*0 
uti 1 i t ies 

stu_$decode_runt ime value 
2-809 

stu_$f indjalock 2-812 
stu $find containing block 
2-8T2 

stu_$f i nd_header 2-813 
stu $find runtime symbol 

" 2-811* 
stu_$get_block 2-815 
stu_$get_J ine 2-817 
stu_$get_l ine_no 2-818 
stu_$get_locat ion 2-819 
stu__$getjnap_i ndex 2-819 
stu_$get_runt ime_address 
2-820 

stu_$get_runt ime__block 

~ 2-821 
stu_$get runtime_line no 
2-822 

stu_$get runt ime_location 
2-823 

stu $get_statement map 

2=821* 

stu_$of f set_to pointer 
2-821* 

stu_$poi nter_to_of f set 
2-825 



debugging (cont) 
utilities 

stu_$remote_format 2-826 
variable information 
runtime symbol info 
2-699 

decode_clock value subroutine 
A-2 
see also 

d a t e_t i me_$ f r om__c 1 oc k 

decode clock value $date time 
A-3 

decode_def i ni tion_ subroutine 
2-208.8 

decode_def ini tion_$decode cref 
2-210 

decode_def i ni t ion_$f ul 1 2-211 

decode_def i n i t i on_$ i n i t 2-213 

decode descriptor subroutine 
2-211* 

def i ne_area__ subroutine 2-215 
delete^ subroutine 2-218 
delete_$path 2-218 
delete_$ptr 2-220 

deleti ng 

d i rectory 

delete_$path 2-218 
hcs_$delentry__f i le A-10 

hei rarchy 

hcs_$de1_di r__tree A-9 

1 i nk 

hcs_$del entry_f i 1 e A-10 
reference name 

hcs_$termi nate_name A- 17 
hcs__$termi nate_noname 
A-18 
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deleting (cont) 
segment 

delete_$path 2-218 
delete_$ptr 2-220 
hcs_$del entry_f i le A-10 
hcs_$del entry_seg A- 11 

deletion 
quer ies 

dl_handler_ 2-231 

dial f ac i 1 i ty 

auto cal 1 channel 

d i a 1 _manager_$d i a 1 __out 
2-222 

di al_manager_$pr i v_attach 
2-223 

dial_manager_$regi stered_s 
2-223 

di al_manager_$release__chan 
2-22i* 

d i a 1 _manager_$ r e 1 ease__chan_n 
2-224 

d i al_manager_$rei ease_d i a 1 id 

2-224 " 

dial_manager_$release_no__l i s 

2-225 ~ 
d i a l_manager_$shutof f _d i a 1 s 
2-225 

di al_manager_$termi nate_d i al 
2-226 

establishing dial line 
dial _manager_$a 1 1 ow_d i a 1 s 
2-221 
event messages 

conver t_d i al_message_ 
2-120 
onl i ne test i ng 

di al_manager_$tandd_attach 
" 2-226 

d i al_manager_ subroutine 
2-220 

dial manager_$al low_dial s 
"2-221 

di al_manager_$dial_out 2-222 



d i al_manager_$pr i vi leged_attach 
2-223 

di al_manager_$release_channel 
2-223 

di al_manager_$rel_chan_no_hangup 
2 _ 22k 

dial_manager_$release_dial_id 
2-224 

di al_manager_$release_jio__l isten 
2-225 

d i al_manager_$shutof f_di al s 
2-225 

d ial_manager_$tandd_attach 
2-226 

d i al_manager_$termi nate_di al_out 
2 _ 226 

d i rectory 

absol ute_pathname_$add__suf f i x 
2-7 

access control 
copy_acl_ 2-126 
hcs_$add_d i r_ac l_entr i es 

" 2-386 
hcs_$add_di r_i nacl__entr i es 

2-388 ~ 
hcs_$get_access_c 1 ass 

" 2-414 
hcs_$ 1 i st_d i r_acl 2-443 
hcs_$ 1 i st_d i r_i nac 1 2-444 
hcs_$repl ace_d i r_acl 

" 2-454 
hcs__$replace_di r__i nacl 

2-456 
access modes 

cv_dir_mode_ 2-165 
author 

hcs_$get_author 2-416*4 
bit count author 

hcs_$get_bc_author 2-417 
copying 

copy_dir_ 2-127 
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directory (cont) 

creati ng 

hcs_$append_branchx 2-393 
hcs_$create_branch_ 2-400 

deleti ng 

delete_ 2-218 
delete_$path 2-218 
hcs_$de1 entry_f i 1 e A-10 

expand_pathname_$add_suf f ix 
2-21*6 

hcs $delete dir acl_entries 
2-404 ■ 

hcs_$delete_di r__i nacl_entr ies 

2-1*05 
hierarchy 

sweep_disk_ 2-838 
information segments 

1 ist_dir_info_ 2-581 
name manipulation 

get_shortest_path_ 2-373 

hcs_$chname_f i 1 e 2-397 
process directory 

get_pdir_ 2-369 
quota 

hcs_$quota_move 2-1*50 . 1 
hcs__$quota_read 2-1*51 
ring brackets 

hcs $get dir r i ng_brackets 

2-hH " 
hcs_$set dir_ring brackets 

2-461 

root directory 

absol ute_pathname_ 2-6 
expand_pathname_ 2-21*5 

safety switch 

hcs_$get_saf ety_sw 2-1*28 
hcs_$set_safety_sw 2-1*69 

status 

hcs_$status_ 2-1*80 
hcs_$status_long 2-484 
hcs_$status_minf 2-1*88 

working directory 

change_def ault_wdi r_ 2-83 
change_wdir_ 2-84 
get_def aul t_wdi r_ 2=352 
get_wdir_ 2-378 

discard_ I/O module 3-33 



disconnected process 

sus signal handl er_$recon_ec 
2-837, 2-838 

disk I/O 

i/0 modules 

rd isk_ 3=122 
i nf ormat ion 

f ind_parti tion_ 2-288 
read label 

phcs $read disk label 

""2-645" 
readi ng 

hphcs_$read_part i t ion 
2-507 

wr i t i ng 

hphcs $write partition 
2-509 

d i sp 1 ay_access_c 1 ass_ 
subroutine 2-229 

di spl ay_access_cl ass__$ range 
2-230 

display_f i le_value_ subroutine 
2-231 

dl_handler_ subroutine 2-231 

dl_handler_$dblstar 2-232 

dl_handler_$dirdelete 2-233 

dprint_ subroutine 2-233 

dprint $check daemon access 
2-239 

dprint_$dprint_ 2-233 

dpr int__$queue_con tents 2-240 

dpr int_$request_id 2-239 

dump_segment subroutine 
2-240 

dump_segment_$str i ng 2-241 
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E 



EBCDIC 

character conversion 

asci i_to_ebcdic_ 2-32.1 
ebcdic_to_asci i_ 2-21*3 

ebcdic_to_asci i_ subroutine 
2-243 

ebcdi c_to_asci i_$ae_table 
2-2i*l* 

effective access mode 

hcs_$get_user_ef fmode 2-1*35 

encode_clock_value_ subroutine 
A-5 

see also date_t ime_$to_clock 

encode_clock_value_$of f sets 
A-6 

enter_abs_request_ subroutine 
2-21*4.1 

enter_abs_request_$enter_abs_r 
2-21*1*. 1 

entry point 

ca 1 1 i ng sequence 

get_entry_arg_descs_ 

2-354 
declare statement 

get_entry__poi nt__dcl_ 

~" 2-359 
entry sequence flags 

get__entry_arg_descs_$ i nf o 
2-355 

get_entry_arg_descs_$text_o 
" 2-358 

get_entry_arg_descs_$text_onl 

" 2-357 
name 

get_entry_name_ 2-358 
poi nter 

hcs_$make_ptr 2-1*1*9 



entry point (cont) 
value 

hcs_$make_entry 2-1*1*8 

entry point bound 
setting 

hcs_$set__entry_bound 
" 2-1*63, 2-1*62.1 

entryname 
entry point 

get_entry_name_ 2-358 
equal names 

get_equal_name_ 2-362 
name dupl i cat ion 

nd_handler_ 2-625 
star names 

check_star_name__ 2-87 

hcs_$star_ 2-1*71 

hcs_$star_di r_l i st_ 2-1*74 

hcs_$star~l ist_ 2-479 

match_star_name_ 2-583 
suf f i xes 

enff ! ua/J w^mA 1-01 I. 

i ■ i n^u I iuiii^ t- \JJH 

epi logue handlers 

add_epi logue_handl er_ 2-11 
execute_epi logue_ 2-245 

equal convention 

get_equal_name_ 2-362 
get_equal_name_$ component 
2-363 

error handl i ng 
command level 
cu_$cl 2-147 
cu_$get_cl_i ntermedi ary 
2-151 

cu__$reset_cl__i ntermedi ary 
2-156 

cu_$set_cl intermediary 
2-157" 

comma nd_query_$ set cp esc_e 
2-94 

condition 2-100.1 
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error messages 
active functions 

act ive_f nc_err_ 2-7 
active fnc err $suppress_name 
"2-9" 

COBOL 

pr i nt_cobol_error_ 2-650 
print cobol error $switch 
2-650 " 
commands 

com_err_ 2-89 
com err $suppress name 
~ 2-90 
condi t ions 

condition interpreter_ 

2-10T 

dial facility 

convert_dial message 
2-120 
mode strings 

mode_str i ng_$get error 
2-612 
name dupl i cat ion 

nd_handler_ 2-625 
returni ng 
convert_status_code 
2-123 
subsystem 

ssu_$abort_l i ne 2-760 
ssu_$abort subsystem 
2-762" 

ssu_$pr i nt_message 2-794 
sub_err_ 2-830 
translators 

lex_error_ 2-565 

event channel 

absentee information 
system_info $abs chn 
2-81*1 " 

blocked 

ipc_$block 2-556 
communication 

dial_manager_ 2-220 
conver s i on 

i pc_$dec 1 ev_wa i t_chn 
2-560 



event channel (cont) 
creati ng 

ipc $create event channel 

- 2 _ 55g - 

cutoff 

ipc_$cutoff 2-560 
deleting 

i pc_$delete_ev_chn 2-560 
enabl ing 

ipc_$ reconnect 2-562 
event messages 

converted ial message^ 
2-T20 
i nformation 

i pc_$read_ev_chn 2-561 
maski ng 

i pc_$mask_ev_ca 1 1 s 2-56 1 

ipc $unmask ev cal Is 

" 2-563 " 
prior i tizing 

ipc_$set_cal 1_pr ior 2-563 

ipc_$set_wai t_pr ior 2-563 
resetting 

ipc__$drain_chn 2-561 
wakeup signal 

hcs_$wakeup 2-1+91 

execute epilogue subroutine 
2-21*5 

exec__com 

subsystem usage 

ssu $execute start up 

*" 2-771* 
ssu $get ec_search_l ist 

" 2-779 " 
ssu $get ec subsystem ptr 

- 2-779 ~ 

ssu_$get_ec_suf f i x 2-780 
ssu_$set ec search list 

2-800 ~ 
ssu $set_ec subsystem_ptr 

2-800 

ssu_$set_ec_suf f ix 2-801 
vers ion 

get_ec_version_ 2-353 

expand pathname_ subroutine 
2-21*5 
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expand_pathname_$add_suf f i x 
2-21*6 

expand_pathname_$component 
2-247 

expand_pathname_$component_a_s 
2-248 

expand_pathname_$expand_pathnam 
2-245 

expans ion 
command 1 i ne 
abbrev_ 2-3 

exponent control 
condi t ion handl i ng 

hcs_$get_exponent__control 

~ 2-418 
hcs_$set_exponent_control 
2-464 

exponent_control_ subroutine 
t. 4^ 

exponent_control_$f aul t_overf low 
2-249 

exponent_control $f aul t_underf 
2-249 

exponent_control_$restart_overf 
2-249 

exponent_control_$restart_ov 
2-249 

exponent_control $restart_un 
2-249 

external symbol 

get_entry_name_ 2-358 
external variables 
creat i ng 

set ext variable $pointer 
~ 2-733 



external variables (cont) 
get_external_var i able__ 
2-366 

set_externa 1_var i abl e_ 
2-731 

set_external var i abl e_$ locate 
2-732 



fault conditions 

exponent_control_$f aul t_ov 
2-249 

exponent_control_$f aul t_un 
2-249 

exponen t_con trol__$restar t_ov 
2-249 

exponent_control_$restar un 
2-249 



f i ie 

i nformation 

di splay_f i le_value_ 2-231 
transf err i ng 

xmodem_io_ 3~285 

file control block 
msf_manager_$close 2-621 
msf_manager_$open 2-623 

f i lejnanager_ subrout i ne 2-250 

f i 1 e_manager_$c 1 ose 2-25 1 

f i 1 e_manager_$create 2-251 

f i 1 e_manager_$create_open 2-254 

f i i e_fiianager_$de i ete_c 1 ose 2-255 

f i le_manager_$f ree 2-255 

f i le_manager_$get 2-256 
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file manager $get ci header 
"2-258 

f i le_manager_$get_ci_ptr 2-260 

file manager $get exclusive 
""2-261 

f i 1 e_manager_$get_stream 2-262 

f i 1 e_manager_$ 1 ock_adv i ce 2-263 

f i lejnanager_$open 2-265 

f i lejnanager_$put 2-266 

f i lejnanager_$put_stream 2-267 

f i le_manager_$raw_get 20 34 

f i le_manager_$raw_put 21 13 

f i lejnanager_$simple_get 22 2 

f i lejnanager_$simple_put 23 2 

f i le_manager_$status 23 39 

f i lejnanager^Sterminate^ei^ptr 
~ 2-273 = 

f i nd_bi t_ subrouti ne 2-274 

f ind_bit_$f irst_off 2-274 

f ind_bi t_$f irst_on 2-271* 

f i nd_b i t_$ 1 ast_of f 2-275 

f ind_bit_$1ast_on 2-275 

find_char_ subroutine 2-276 

f ind_char_$f irst in list 
2-277 



find char $first in table 
~2-280 

find char $first not in list 
"2-278 

f i nd_char_$ 1 ast__i n_l i st 2-278 

find char $last in table 
~2-280 

find char $last not in list 
"2-279 

find char $make tab chars in 1 
" 2-282 

find char $make tab char not in 1 
2-283 

find char $not ascii table 
"2-284 

find_char $translate first in tab 
2-281 

find char $trans1ate last in t 
~ 2-282 

f i nd_cond i t i on_f r ame_ 
subroutine 2-284 

f i nd_cond i t i on__i nf o_ 
subroutine 2-285 

find include file subroutine 
"2-287 

find_include file $init count 
2-287 

f i nd_parti tion subroutine 
2-288 

find source file subroutine 
"2-289 ~ 

find source file $search path 
~2-290 " 
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formatted output 
character string 
ioa_ 2-518 

ioa_$general_rs 2-519 
ioa_$ ioa_stream 2-520.1 
ioa_$ ioa_stream_nnl 

2-520.1 
ioa_$ioa_swi tch 2-520.1 
i oa_$ i oa_sw i tch_nn 1 

2-520.1 
ioa_$nnl 2-518 
ioa_$rs 2-521 
ioa_$rsnnl 2-521 
ioa_$rsnp 2-521 
ioa_$rsnpnnl 2-521 

numbers 

numer ic_to_asci i__ 2-627 
numer i c_to_asc i i _base_ 
2-628 

segment dump 

dump_segment_ 2-22*0 

text 

forma t_document_ 2-290.1 
format document $string 

2-290.2 
f ormat_document_$swi tch 

2-290.3 

f ormat_document_ subroutine 
2-290.1 

f ormat_document_$str i ng 
2-290.2 

f ormat_document_$swi tch 
2-290.3 

f ortran 
arrays 

hcs_$set__256K_swi tch 
2-2*59 

data type conversion 
ass i gn_$computat i ona l_ 
2-49 

symbol information 
runt ime_symbol info 
2-699 

fs_uti 1_ subroutine 2-290.10 



fs_ 


uti 




2- 


f s_ 


uti 




2 


fs_ 


_uti 


f s 


ut i 


fs. 


_uti 


fs_ 


ut! 




2 


f s 


ut i 


fs. 


_uti 


fs. 


uti 




2 


1 s 


ut! 


fs. 


_uti 


fs 


uti 



f s_ut i 

f s_ut i 
2 

f s__ut i 

f s_ut i 
2 

f s_ut i 

f s_ut i 
2 

f s_ut i 

fs uti 
2 



_$add_acl_entr ies 
290.10 

__$add ext_ad_entr ies 
292 

_$chname_f i le 2-294 

_$copy 2-294 

_$delentry_f i le 2-298 

_$delete_ac1 entries 
297 

_$get_bi t__count 2-299 

_$get_max_length 2-299 

_$get_r i ng_brackets 
300 

_$get_switch 2-301 

_$get_type 2-301 

_$get_user_access_modes 
-302 

_$list_acl 2-303 

_$1 i st_extended_acl 
304 

_$1 i st_swi tches 2-305 

_$ 1 i st_swi tches_f or_type 
307 

_$make_entry 2-308 

$make_entry_f or_type 
,309 

_$replace_acl 2-309 

_$repl ace_extended_acl 
-310 



i -22 



AG93-05A 



s_uti l_$set_bi t_count 2-311 

s_uti l_$setjnax_length 2-312 

s_uti 1 $set r ing_brackets 
2-312 

s_uti l_$set_swi ten 2-313 

s.uti l_$suff ix_info 2-313 

s util $suffix info for type 
2-316 

t_menu_ subroutine 2-316 
t_menu_$ create 2-317 
t_menu_$del ete 2-319 
t_menu_$descr ibe 2-319 
t_menu_$destroy 2-320 
t_menu_$di splay 2-321 
t__menu_$get_choi ce 2-321 
: t_menu_$ i n i 1 1 2-322 
t_menu_$ i n i t2 2-322 
t_menu_$l ist 2-321* 
tjnenu_$ retrieve 2-325 
t_menu_$ store 2-325 
: t_menu_$termi nate 2-327 
: t__window_ subroutine 2-328 
: t_window_$ change 2-328 
; t_wi ndow_$cl.ear_wi ndow 2-329 
t_window_$ create 2-329 
: t_window_$ destroy 2-330 



G 



gll5_ I/O module 3-34.1 

generic math_ subroutine 
2-341 

generic math $add binary 
2-347 

generic math $add binary comp 
2-348 

generic math $add decimal 
2-342 

generic math $add decimal comp 
2-343 " 

gener i c_math_$d i v i de_b i nary 
2-350 

generic math_$divide binary c 
2-351 

generic math $divide decimal 
2-345 

generic math $di vide decimal c 
2-346 ~ 

gener ic_math $mul tiply_binary 
2-349 

gener ic_math $mul t i ply_bi nary c 
2-350 

gener i c_math_$mu 1 1 i pi y_dec i ma 1 
2-344, 2-345 

generic math_$negate__bi nary 
2-346 

gener ic_math_$negate binary_c 
2-347 

generic math_$negate_decimal 
2-342 
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gener i c_math_$negate__decimal_c 
2-342 ~ 

gener i c_math_$subtract_bi nary 
2-348 

gener i c_math_$subtract_b i n_c 
2-349 

gener i c_math_$subtrac t_dec i ma 1 
2-343, 2-344 

get bound_seg_i nfo_ subroutine 
2-351 

get_def aul t_wdi r_ function 
~ 2-352 ' 

get_def i ni t ion_ subroutine 
2-353 

get_ec__vers ion_ subroutine 
2-353 

get_entry_arg__descs_ 
subroutine 2-354 

get_entry_arg_descs_$ i nf o 
" 2-355 

get_entry_arg_descs_$text__only 
2-357, 2-358 " 

g e t_e n t r y_a r g_d e s c_$ g e t_e_a_d 
" 2-354 

ge t_entry_name_ subroutine 
2-358 

get_entry_poi nt_dcl_ 
subroutine 2-359 

get_equal_name_ subroutine 
2-362 

get equal name $component 
2-363 



get_external__var iable_ 
subroutine 2-366 

get_group_id_ function 2-366 

get_group_id_$tag_star 2-367 

get_ini tial__ring_ subroutine 
2-367 

get_l i ne_length_ function 
2-368 

get_l i ne_length_$stream 2-368 

get__l ine_length_$swi ten 2-368 

get_lock_id_ subroutine 2-369 

get_pdir_ function 2-369 

get_pr i vi leges_ function 
2-370 * 

get_process_access_c 1 ass_ 
function 2-371 

get_process_author i zat i on__ 
function 2-372 

get_process__id_ function 
" 2-372 " 

get_process__max_author i zat i on_ 
function 2-372 

ge t_r i ng_ function 2-373 

get_shortest_path_ 2-373 

get_shortest_path_ subroutine 
2-373 

get_system_aim__attr ibutes_ 
subroutine 2-374 

get_system_f ree_area_ function 
2-376 
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get_temp_segments_ subroutine 
"~ 2-377 

get_temp_segment_ subroutine 
2-376 

get_wdir_ function 2-378 



H 



handl ers 
cleanup 

execute_epi logue_ 2-2k5 
deletion situations 

dl_handler_ 2-231 
machine conditions 

prepare_mc_restar t_ 2-647 

signal^ 2-741 
name dupl i cation 

nd_Jiandler_ 2-625 
process termination 

add_ep i 1 ogue_hand 1 er_ 
2-11 

run uni t termi nat i on 
add epi 1 ogue_handl er_ 
2-11 
static handlers 

sct_manager_ 2-712 

set manager $cal 1 handler 

* 2-712 
sus_signal_handler_ 2-837 

hardcore segments 
i nformat ion 
ringO_get_ 2-687 
r i ng_zero_peek_ 2-693 

hardware-detected condition 
prepare_mc__restart_ 2-647 

hash table 
hash__ 2-379 
hash_index_ 2-383 
rehash_ 2-671 

hash_ subroutine 2-379 



hash_$in 2-379 

hash_$ i nagai n 2-380 

hash_$make 2-381 

hash_$opt_size 2-381 

hash_$out 2-382 

hash_$search 2-382 

hash_index_ subroutine 2-383 

HASP communications 
hasp_host__ 3"36 
hasp_workstat ion__ 3~44 

hasp_host_ 3~36 

hasp_host_ I/O module 3-36 

hasp_workstat ion_ 3~44 

hasp_works tat i on_ I/O module 
3-44 

hcs_$add_acl_entr i es 2~384 

hcs_$add_di r_acl_entr i es 
" 2-386 

hcs_$add_di r i nac l__entr i es 
2-388 

hcs_$add_i nacl__entr i es 2-390 
hcs_$append_b ranch 2-392 
hcs_$append_branchx 2-393 
hcs_$append_l i nk 2-395 
hcs_$change_bc_seg 2-396 
hcs_$chname_f i le 2-397 
hcs_$chname_seg 2-399 
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hcs_$create_branch_ 2-1*00 

hcs_$del entry_f i 1 e A- 10 
see also delete_$path 

hcs_$del er.tr y_seg A- 1 1 
see also delete_$ptr 

hcs_$delete_ad_entr ies 2-1*03 

hcs $delete_dir acl entries 
2-1*01* 

hcs_$del ete_di r_i nacl_entr i es 
2-405 

hcs_$delete_inacl_entr ies 
2-406 " 

hcs_$del_di r_tree A-9 
see also del ete_$path 

hcs_$f orce_wr i te 2-1*07 

hcs_$f s_get_mode 2-1*09 

hcs_$f s_get_path_name 2-1*10 

hcs__$f s_get_ref__name 2-1*11 

hcs_$f s_get_seg_ptr 2-1*11 

hcs_$f s_move_f i le 2-1*12 

hcs_$f sjnove__seg 2-1*11* 

hcs_$get_access__cl ass 2-1*11* 

hcs_$get__access class_seg 
2-1*15 

hcs_$get_access_i nf o 2-1*16 

hcs $get_access_info seg 
~ 2-1*16.2 

hcs_$get_author 2-1*16.1* 

hcs_$get_bc_author 2-1*17 



hcs_$get_d i r__r i ng__brackets 
2-1*17 

hcs_$get_exponent__control 
2-1*18 

hcs__$get_i ni t i al_r i ng 2-1*19 

hcs_$get_i psjnask 2-1*19 

hcs__$getj i nk_target 2-1*20 

hcs_$get_max_length 2-1*21 

hcs_$get_max_J ength_seg 2-1*22 

hcs_$get_page_trace 2-1*22 

hcs_$get_process_usage 2-1*21* 

hcs_$get_r i ng_brackets 2-1*27 

hcs__$get_r i ng_brackets_seg 
*-l**/ 

hcs_$get_saf ety_sw 2-1*28 

h c s_$ g e t_s a f e t y __s w_s eg 
~ 2-1*28.1 

hcs_$get_search_rules 2-1*29 

hcs_$get_system search rules 
~ 2-430 

hcs_$get_uid_f i le 2-1*31 

hcs_$get_uid_seg 2-1*32 

hcs_$get_user access_modes 
2-1*32 

hcs $get_user_access_modes ptr 
2-433 

hcs_$get_user_ef fmode 2-1*35 
hcs_$h i gh_low_seg_count 2-1*36 
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hcs_$history_regs_get 2-436.1 

hcs_$history_regs_set 2-437 

hcs_$ini tiate 2-437, A- 1 1 

hcs_$ini tiate_count 2-439, 
A- 13 

hcs $ i ni ti ate_search_rul es 
~ 2-440 

hcs_$l ist_ad 2-442 

hcs_$l ist_dir_acl 2-443 

hcs_$l ist_dir_inacl 2-444 

hcs_$ 1 i st_i nac 1 2-446 

hcs_$lv_attached 2-447 

hcs_$make_entry 2-448 

hcs_$make_ptr 2-449 

hcs_$make_seg 2-450 

hcs_$quota__move 2-450.1 

hcs_$Cjuo t5_r ead 2~45 1 

hcs_$rel ease__segment__numbers 
2-452 

hcs__$replace_acl 2-453 

hcs_$replace_di r_acl 2-454 

hcs__$replace_di r__i nacl 2-456 

hcs_$replace_inacl 2-457 

hcs_$reserve_segment numbers 
2-458 

hcs_$reset_i ps_mask 2-458 
hcs_$set_256K_swi tch 2-459 



hcs_$set_bc 2-460 

hcs_$set_bc_seg A- 14 
see also termi nate_f i 1 e_ 

hcs_$set_d i r_r i ng_brackets 
2-461 

hes_$set_dnzp_sw 2-462 

hcs_$set_dnzp_sw_seg 2-462.1 

hcs_$set_entry_bound 2-462.1 

h c s_$ s e t_e n t r y__bou nd_s eg 
2-463 

hcs_$set_exponent_control 
2-464 

hcs_$set_i psjnask 2-465 

hcs_$set_max_l ength 2-466 

hcs_$set_max_l ength_seg 2-467 

hcs_$set_r i ng_brackets 2-468 

hcs_$set_saf ety_sw 2-469 

hes_$set_saf ety_sw_seg 2-470 

hcs_$star_ 2-471 

hcs_$status__ 2-480 

hcs_$status_long 2-484 

hcs_$status__mi nf 2-488 

hcs_$status_mi ns 2-489 

hcs_$termi nate_f i 1 e A- 16 
see also term_ 

hcs_$ termi nate_name A- 17 
see also term__$ref name 

hcs__$ termi nate_noname A-18 
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hcs_$termi nate_seg A- 19 
see also term_$seg_ptr 

hcs_$truncate_f i le 2-1+90 

hcs_$truncate_seg A- 19 
see also termi nate_f i 1 e_ 

hcs_$val idate_process id 2-1+91 

hcs_$wakeup 2-J+9 1 

hcs_change_bc 2-395 

HEAPSORT algorithm 
sort_items_ 2-742 
sort_i tems_i ndi rect_ 
2-742.6 

heap_manager$pop_heap_l evel 
2-492 

heap_manager_ 2-492 

heap_manager_$get_heap_area 
2-494 

heapjnanager_$get_heap_header 
2-493 

heap_manager_$get_heap_l evel 
2-494 

heap_manager $push__heap__l eve I 
2-492 

help_ subroutine 2-495 

help_$check_info_segs 2-502.3 

help_$init 2-505 

help_$term 2-506 

h i erarchy 
copy i ng 

copy_dir_ 2-127 
deleti ng 

hcs_$del_di r_tree A-9 



hierarchy (cont) 
wa 1 k i ng 

sweep_disk_ 2-838 

history registers 

hcs_$hi story_regs_get 
2-436.1 

hcs_$h i story_regs_set 2-437 

home directory 

change_wdir_ 2-84 

hphcs_$ i ps_wakeup 2-507 

hphcs_$read_part i tion 2-507 

hphcs_$wr i te_part i t ion 2-509 



I 



1/0 

asking questions 

command_query__ 2-91 

attachments 

i ox_$attach_name 2-533 
iox__$attach__ptr 2-534 
iox_$ i ni t_standard_i ocbs 
2-542 

i ox_$move_attach 2-544 

cleanup 

iox_$close 2-535 

1 ox_$destroy_i ocb 2-537 

iox_$detach_iocb 2-538 

closing 

iox_$close 2-535 

control block 

iox_$destroy_iocb 2-537 
i ox_$detach__i ocb 2-538 
iox_$f i nd_iocb 2-539 
i ox_$f i nd_i ocb_n 2-540 
i ox_$ i ni t_standard_i ocbs 
2-542 

iox_$look__iocb 2-543 
i ox_$propagate 2-549 
pi l_i o_$get_i ocb_ptr 
~ 2-646 
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I/O (cont) 
control order operations 

iox_$control 2-536 
daemon 

dpr i nt_ 2-233 

hasp_workstat ion_ 3"44 

iod_info_ 2-529 
error messages 

act i ve_f nc_err_ 2-7 

act i ve_f nc_err_$suppress_name 
2-9 

com__err__ 2-89 
com_er r_$ suppr ess_name 
2-90 

convert_status_code_ 
2-123 

cv_error_$name 2-168 
iox_$err_not_attached 
2-538 

iox_$err_not_closed 2-538 
iox_$err_not_open 2-538 
i ox_$er r_no_opera t i on 

" 2-538 
lex_error_ 2-565 
sub__err_ 2-830 

file" 

vfile_ 3-219 

formatted output 

dump_segment_ 2-2kO 
f ormat_document__ 2-290.1 

r *> _ r 1 ft 

ioa_ /L ^ iq 

numer i c_to_asc i i_ 2-627 
numer ic_to_asci i_base__ 
2-628 

i nput 
ask_ 2-37 

iox_$get_chars 2-540 
iox_$get_l i ne 2-54 1 
iox_$read_record 2-55 1 
l i ne length 
get_l i ne_l ength_ 2-368 
get_l i ne_l ength_$ stream 

" 2-368 
get line length $switch 
" 2-368 

modes 

iox_$modes 2-543 
tty_ 3-187 



I/O (cont) 

openi ng 

iox_$open 2-545 

output 

i ox_$put_chars 2-549 
iox_$rewr i te_record 2-553 
iox_$wr i te_record 2-555 

record 

iox_$del ete_record 2=537 
iox_$posi tion 2~547 
iox__$read_key 2-550 
iox_$read_length 2-55 1 
i ox_$read_record 2~55l 
iox_$rewr i te_record 2-553 
iox_$seek_key 2-553 
i ox_$wr i te_record 2-555 

resource 

resource_control_ 2-675 
resource_i nf o_ 2-682 

r i ngs 

cross__ring_ 3~32 

cross__r i ng_io_$al low_cross 

2-136 

storage system 
vfile_ 3-219 

stream I/O 

iox_$get_chars 2-540 
iox_$get_l i ne 2-54 l 
iox_$put_chars 2-549 

synonym attachment 

■> _ \ r *» 

=» X 1 1 

termi nal 

ask_ 2-37 

ioa_ 2-518 

tty_ 3-187 
useless output 

discard^ 3~33 

1/0 daemon 
dpr i nt_$check_daemon_access 

2-239 
HASP communications 

hasp_workstation_ 3~44 
iod i nf o_$dr i ver_access__name 
2-529 

pr i ces 

system_i nf o_$ i o_pr i ces 
2-844 
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I/O daemon (cont) 
queue 

dpr i nt_$queue_contents 
2-240 

i od__i nf o_$queue_data 
2-530 
request types 

i od_i nf o_$gener i c__type 
~ 2-530 

iod_i nfo_$rqt_l i st 2-531 
requests 

dprint_ 2-233 
tables 

iod_info_ 2~529 

I/O modules 
ansi_tape_io_ 3~3 
audit_ 3-23 
bisync_ 3"27 
cross_ring_ 3"32 
discard^ 3-33 

gii5_ 3-34.1 

hasp_host_ 3-36 
h35p_wor kstat i on_ 3 _ 44 
ibm2780_ 3"74 
ibm3270_ 3-77 
ibm3780_ 3-86 
mtape_ 3-89 
rbf_ 3-H8 
rdisk_ 3-122 
record_stream_ 3" 132 
remote_i nput_ 3- 1 36 
remote__pr i nter_ 3" 138 
remote_punch_ 3" i 44 
remote_tel epr i nter_ 3" 146 
syn_ 3-152 
tape_ans i_ 3- 15 1 
tape_ibm_ 3-161 
tape_mult_ 3-176 
tape_nstd__ 3-180 
tc io_ 3-185 
tty_ 3-187 
tty_printer_ 3-217 
vfile_ 3-219 
window_io_ 3-263 
xmodem_io_ 3-285 



IBM PC-to-Host 
data transfer protocol 
ibm_pc_io_ 3-5 1 

IBM per-format module (PFM) 
ibm_tape_io_ 3"55 

IBM PFM 

see IBM per-format module 

ibm2780_ I/O module 3-74 

ibm3270_ I/O module 3-77 

ibm3780_ I/O module 3-86 

ibm_pc_io_ I/O module 3-5 1 

ibm__tape_io_ I/O module 3-55 

info directories 
subsystem 

ssu_$add_info_di r 2-763 

information 

retr i evi ng onl i ne 
help_ 2-495 
hel p_$check__i nf o_segs 

2-502.3 
help_$init 2-505 
help_$term 2-506 
system 

system_info_ 2-840 

ini tiate_f i le_ subroutine 
2-510 

i n i t i ate_f i 1 e__$component 
2-511 

ini tiate_f i le_$create 2-5 1 3 

input string 
pars i ng 

lex_string_ 2-569 

i nterpret_resource_desc_ 
subroutine 2-514 
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interprocess communication 
faci 1 i ty 

ipc_ 2-556 
wakeup signal 

hcs_$wakeup 2-i+9 1 

ioa_ subroutine 2-518 

ioa_$nnl 2-518 

ioa_$general_rs 2-519 

ioa_$general_rs_control_str i ng 
2 _ 520 

ioa_$ ioa_stream 2-520.1 

ioa_$ ioa_stream_nnl 2-520.1 

ioa_$ ioa_swi tch 2-520.1 

ioa_$ ioa_swi tch_nnl 2-520.1 

ioa_$nnl 2-518 

iod_info_ subroutine 2-529 

i od_i nf o_$dr i ver__access_name 
2-529 

jod info $generic type 2-530 

i od_i nf o_$queue_data 2-530 

iod_info_$rqt_l i st 2-531 

I0M channel 
parse_i o_channel_name 
2-642.12 

iox_ subroutine 2-532 

iox_$attach_loud 2-533 

iox_$attach_name 2-533 

iox_$attach_ptr 2-531* 

iox_$close 2-535 



iox_$close_f i le 2-535 

iox_$control 2-536 

iox_$delete_record 2-537 

iox_$destroy_iocb 2-537 

iox_$detach 2-538 

iox_$detach_iocb 2-538 

i ox_$err_not_att ached 2-538 

iox_$err _not_closed 2-538 

iox_$err_not_open 2-538 

iox_$err_no_operat ion 2-538 

iox_$f i nd_iocb 2-539 

iox_$f i nd_iocb_n 2-540 

iox_$get_chars 2-540 

iox_$get_l i ne 2-541 

iox_$ i ni t_standard_iocbs 
2-51*2 

iox_$look__iocb 2-543 
iox_$modes 2-543 
iox__$move__attach 2-544 
iox_$open 2-545 
i ox_$open_f i 1 e 2-546 
iox_$pos i tion 2-547 
iox_$propagate 2-549 
iox_$put_chars 2-549 
iox_$read_key 2-550 
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iox_$read_length 2-551 

iox_$read_record 2-551 

i ox_$rewr i te_record 2-553 

iox_$seek__key 2-553 

iox_$wr i te_record 2-555 

ipc_ subroutine 2-556 

ipc_$block 2-556 

i pc_$create_event_channel 
~ 2-558 ~ 

ipc_$cutoff 2-560 

i pc_$decl_ev_wai t_chn 2-560 

ipc_$delete_ev_chn 2-560 

: _j : _ _ i i r z' 1 

i vui ani_v.nn _ jo' 

i pc_$mask_ev_ca 1 1 s 2-56 1 

i pc_$read_ev_chn 2-561 

i P c _$ reconnect 2~562 

i pc_$set_cal l_pr ior 2-563 

i pc_$set_wai tjpr ior 2-563 

i pc_$unmask_ev_cal 1 s 2-563 

ips signal 

create__i ps_mask_ 2-135 
hcs_$get__i psjnask 2-1+19 
hcs_$reset_i ps_mask 2-1*58 
hcs_$set_i ps_mask 2-1*65 



L 



1 anguages 
break characters 

1ex_string_ 2-569 
error messages 

lex_error_ 2-565 
translator uti 1 i ties 

f ind_include_f i le_ 2-287 

f i nd_source_f i 1 e_ 2-289 

lex_error_ subroutine 2-565 

1 ex_str i ng_ subroutine 2-569 

lex_string__$ini t_lex_del ims 
2-569 

lex_str ing_$lex 2-571 

1 ibrar i es 
search rules 

hcs__$ i n i t i a te_search_rul es 
2-1*1*0 

link 

creat i ng 

hcs_$append_l i nk 2~395 

delet i ng 

delete_ 2-218 
delete_$path 2-218 
hcs_$delentry_f i le A- 10 

i nf ormat i on 

1 ist_dir_info_ 2-581 

1 i nks 
author 

hcs_$get_author 2-1+16.1* 
bi t count author 

hcs_$get_bc_author 2-1*17 
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links (cont) 
restor i ng 

link_unsnap_ A-2C 
target pathname 

hcs_$get_l ink_target 
2-1*20 
unsnappi ng 

term_ 2-853 

term_$ref name 2-853 

term_$unsnap 2-855 

1 i nk_unsnap__ subrouti ne A-20 
see also term_$unsnap 

1 ist_dir_info_ subroutine 
2-581 

lock i ng 
ident i f i er 

get_lock_id_ 2-369 
see also ips signal 
set_lock_ 2-737 
set_lock_$lock 2-738 
set_lock_$unlock 2-7^0 

logical volume 
check i ng 

hcs_$lv_attached 2-447 

mdc_$check_mounted 2-584 
effective access 

mdc ^"""et Iv access 
"1-586.1 
identi f ier 

mdc_$f ind_lvid 2-586.1 
quota 

mdc_$set_volume_quota 
2-588 



machine conditions 
check i ng 

prepare__mc_restart_ 2-647 
messages 

condi t ion_i nterpreter_ 
2-101 



machine conditions (cont) 
restart i ng 

prepare_mc_restart_$replace 
2-648 

prepare_mc_res tar t_$ retry 
2-648 

prepare_mc_restart_$tra 

2-649 
s i gnal 1 i ng 

signal^ 2-741 
static handlers 

sct_manager_ 2-712 
trac i ng 

f i nd_condi tion_i nfo_ 
2-285 

magnetic tape 
I/O modules 
ans i_tape_i o_ 3"3 
i bm_tape__ i o_ 3~55 
mtape_ 3-89 
tape_ansi__ 3" 151 
tape_ibm_ 3" 161 
tape_mult_ 3" 176 
tape_nstd_ 3-180 

mai 1 f aci 1 i ty 

send_mail_ 2-722.1 
send_mai l_$access_cl ass 
2-723 

conH ma! 1 ^nath 0 — 701. 

send_mai l_$path_access_cl ass 
2-724 

master directories 

i nf ormat ion 
mdc__$pvname_i nf o 2-586.2 

mani pul at ion 

mdc_$create_di r 2-585 
mdc_$create_di rx 2-586 
mdc_$delete_dir 2-586 

owner 

mdc_$set_mdi r_owner 2-587 
quota 

mdc__$set_mdi r_account 

~ 2-586.3 
mdc_$set_mdi r_quota 2-588 
md c_$ s e t_vo 1 ume_q uo t a 
2-588 
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match_star_name_ subroutine 
2-583 

mdc_ subroutine 2-584 
mdc_$check_mounted 2-584 
mdc__$create_di r 2-585 
mdc_$create_di rx 2-586 
mdc_$delete_di r 2-586 
mdc_$f indjvid 2-586-1 
mdc_$get_lv_access 2-586 • 1 
mdc_$pvname_i nf o 2-586.2 
mdc_$set_md i r_ac count 2~586»3 
mdc_$set_mdi r_owner 2-587 

i _ x. i ; „ -iron 

mdc__$set_vol ume_quota 2-588 
menu_ subroutine 2-589 
menu_$create 2-589 
menu_$delete 2-591 
menu_$descr i be 2-591 
menu__$destroy 2-592 
menu_$di spl ay 2-592 
menu_$get_choi ce 2-593 
menu_$list 2-594 
menu_$retr i eve 2-595 
menu_$store 2-595 



messages 

event messages 

converted i a l_message__ 
2-120 
i nteract i ve 

send_mai1_ 2-722.1 
sendjnai l_$access__cl ass 
2-723 

sendjnai l_$path 2-724 
i nteruser 

send_message_ 2-727 
send message $acknowledge 

"2-728 
send_message__$express 
2-728 

sendjnessage_$not i f y_mai 1 
2-729 

see also error messages 
send__mai l_$path_access_cl ass 
~" 2-724 

meter i ng 

cpu_t i me_and_pag i ng_ 2-130 

meter i ng_uti 1_ subroutine 
2-599 

meter i ng_ut i l_$def i ne_regions 
2-600 

meter i ngjjt i l_$f i 1 l_buf f ers 
2-602 

meter i ng_uti l_$reset 2-603 

meter_gate__ subroutine 2-603 

mhcs_$get_seg__usage 2-604 

mhcs_$get_seg_usage_ptr 2-605 

microcomputer 
to Multics 

ibm_pc_io_ 3"51 

xmodem_jo_ 3"285 

mlr subroutine 2-606 
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mode strings 

mode_s tr i ng_$ comb i ne 2-610 
mode_str i ng_$del ete 2-611 
mode_str i ng_$get 2-61 1 
mode_str i ng_$get_error 

"2-612 ° 
mode__str i ng_$get_mode 2-612 
mode_str i ng_$parse 2-613 

modes 

I/O switch 

iox_$modes 2-543 
termi nal 
tty_ 3-187 

mode_string_ subroutine 2-607 

mode__str i ng_$combi ne 2-610 

mode_str i ng__$delete 2-611 

mode__str i ng_$get 2-611 

mode_str i ng_$get_error 2-612 

models tr i ng_$get_mode 2-612 

mode_str i ng_$ parse 2-613 

mrl_ subroutine 2-614 

MSF 

see multi segment file 

msf_manager_ subroutine 2-615 

msf_manager_$acl_add 2-615 

msf_manager__$acl_delete 2-617 

msf_manager_$acl_l i st 2-618 

msf_manager $acl_replace 
2-619 ~ 

msf_manager__$adjust 2-620 
msf _manager__$c lose 2-621 



msf_manager_$get_ptr 2-621 

msf_manager_$msf_get_ptr 
- 2 _ 622 - 

msf_manager_$open 2-623 

mtape_ I/O module 3™89 

Mul tics 

to microcomputer 
ibm_pc_io_ 3"51 
xmodem_io_ 3~285 

Multics supervisor 
ring0__get_ 2-687 
r i ng_zero_peek_ 2-693 

multiple names 

hcs__$chname__f i 1 e 2-397 
hcs_$chname_seg 2-399 

mul ti segment file 
author 

hcs__$get_author 2-lf 16-4 
bit count author 

hcs_$get_bc__author 2-417 
generat i on 

ocu_ 2-636 

mu 1 1 i segment file (MSF) 
access control 
copy__acl_ 2-126 
msf_manager_$acl_add 
2-615 

msf manager $ac 1 de 1 ete 

2-617 ' 
msf_manager_$ac 1_1 ist 

2-618 

msf manager_$acl_rep lace 
2-619 

accessing components 
msf manager_$get ptr 

~ 2-621 
msf_manager $msf get_ptr 
2-622 ~ 

cl eanup 

msfjnanager^Sadjust 2-620 
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multi segment file (MSF) (cont) 
closi ng 

msf__manager_$close 2-621 
open i ng 

msf_manager_$open 2-623 

mvt_ subroutine 2-621+ 

mvt $make_translat ion_table 
" 2-621* 



N 



name dupl i cat ion 
handl er 

nd_handler_ 2-625 
nd_handler_$del 2-626 
nd_hand ler_$del_f orce 
2-626 

nd_handl er_$f orce 2-627 

— T _ ~ ~ , „ „ 4- '• 

liailliny ^wnveiiLiviig 

equal names 

get_equal_name_ 2-362 

star names 

check_star__name_ 2-87 
hcs_$star_ 2-1+71 
hcs_$star_dir_l ist_ 2-1+71+ 
hcs_$star_l ist_ 2-1+79 
match_star_name_ 2-583 

nri_handler_ subroutine 2-625 

nd_handler_$del 2-626 

nd_handl er_$del__f orce 2-626 

nd_handler__$force 2-627 

ntape_ 

see tape_nstd__ 

numbers 
convers i on 

ar i thmetic_to_asci i_ 2-31 

assign_ 2-1+8 

ass i gn_round_ 2~50 



numbers (cont) 

conversion 

ass i gn_truncate_ 2-50 
char_to_numer ic_ 2-85 
cv_bin_ 2-161 
cv_dec_ 2-162 
cv_dec_check_ 2-163 
cv_f loat_double_ 2-169 
cv_hex_ 2-171 
cv_hex_check_ 2-171 
cv_oct_ 2-173 
cv_pct_check_ 2-173 

formatted output 

numer i c_to_asci i_ 2-627 
numer i c_to_asc i i _base 
2-628 

f ormatt i ng 
ioa_ 2-518 

random numbers 
random_ 2-658 

sort i ng 

sort__i tems_$f ixed_bin 
2-71+2.2 

sort items indirect ixed b 
" 2-747 

sort_i tems_Jndi rect_$f loat_b 
" 2-747 

numer i c_to_asc i i subrout i ne 
2-627 

numer ic_to_asci i_base__ 
subroutine 2-628 



0 



object segment 
creat i ng 

create data_segment_ 
2-131 

decode_def i n i t i on_$decode_cref 

2-210 
def i nit ion 

decode_def i n i t i on_ 

2-208.8 
decode_def i ni t i on_$ful 1 
2-211 
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object segment (cont) 
generation 

ocu_ 2-636 
i nformat ion 
component^ nf o__ 2-96 
decode_def i n i t i on_ 

2-208.8 
get_bound_seg_i nf o_ 2-351 
object_i nf o_$br i ef 2-630 
object info $di splay 

2 r 630 ~~ 
object_i rifo_$ long 2-631 
ini tial ization 
decode_def i n i t i on_$ i n i t 
2-213 

stu_$get_impl i ci t_qual i f i er 

2-815 
symbol information 
4 runt ime_symbol_i nfo_ 

2-699 
symbol table 

s tu_$decode_r un t i me_ya 1 ue 
2-809 

stu_$f ind_block 2-812 
stu_$f i nd_contai ni ng_block 
2-812 

stu_$f i nd_header 2-813 
stu_$f i nd_runt ime_symbol 

~ 2-814 
stu_$get_block 2-815 
stu $get line 2-81? 
stu_$get__l i ne__no 2-818 
stu_$get_location 2-819 
stu_$get_map_i ndex 2-819 
stu_$get_runt ime_address 
2-820 

stu_$get_runt ime_block 
2-821 

stu_$get_runt ime_l ine_no 
2-822 

s tu_$get_runt ime_1 ocat i on 
2-823 

stu $get_statementjnap 

~ 2-821+ 
stu_$of f se t_to_po i nter 

~ 2-824 " 
stu_$poi nter_to_of f set 
2-825 

stu_$remote_format 2-826 



object_info_ subroutine 2-630 

object__info_$br ief 2-630 

object_i nf o_$di splay 2-630 

object_i nfo_$long 2-631 

ocu_ 2-636 

ocu_$close 2-637 

ocu_$create_msf 2-638 

ocu_$emi t_def ini tion 2-639 

ocu_$emi t_f i rstref_trap 2-640 

ocu_$emi t_l i nk 2-641 

ocu_$emi t_msf_map 2-642.5 

ocu_$emi t_partial_l ink 2-642 

ocu_$emi t_segname 2-642.2 

ocu_$emi t_stat i c 2-642.2 

ocu__$emi t_symbol 2-642.3 

ocu_$emi t_text 2-642.4 

ocu_$open 2-642.5 

ocu_$patch 2-636 

ocu_$release 2-642.7 

on- 1 i ne i nformat i on 
help_ 2-495 

overflows 

exponent_control $fau1t_overf 
2-249 

exponent controi_$restar t overf 
2-249 
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p 



page faults 
moni tor i ng 

cpu_t ime_and_paging 2-130 
segments 

mhcs_$get_seg_usage 2-601* 
mhcs_$get_seg_usage_ptr 
2-605 

page trace 

hcs_$get_page_trace 2-422 

pages 

f lushi ng 

hcs_$f orce__wr i te 2-1+07 
queueing for I/O 

shcs_$set_f orce_wr i te__l imi t 
i mi t 2-741 

parse_file_ subroutine 
2-642.7 

parse_f i 1 e_$parse_f i 1 e_c__l i ne 
2-642.8 

parse_f i le_$parse_f i 1 e__ i n i t_n 
2-642.8 

parse_f i 1 e_$parse_f i le_ini t__ptr 
2-642.9 

parse file $parse_fi I e I ine_no 

"2-642.10 

parse_f i le_$parse_f i le_ptr 
2-642.9 

parse__f i 1 e_$parse_f i 1 e_set_b 
2-642.10 

parse_f i 1 e_$parse_f i 1 e_unset_b 
2-642.11 

parse_io_channe1__name_ 

subroutine 2-642.12 



pars i ng 

ASCII text 

parse_file_ 2-642.7 
character string 
lex_string_ 2-569 
parse_i o_channel_name_ 
2-642.12 

Pascal 

runt ime_symbol_i nf o_$f ather_type 
2-705 

runt ime_symbol_i nfo_$successor 

2-708 
symbol information 
runt ime_symbol_i nf o_ 

2-699 
text file 

pascal_util_ 2-642.13 

pascal_uti l|breakal l_of f 
2-642.15 

pascal__uti l^breakal l_on 

t r i *» \ r 

pascal _ut i l^establ i sh_on_uni t 
2-642.13 

pascal_uti l$remove_on_uni t 
2-642.14 

pascal_util subroutine 
2-642.13 

passwords 

read_password_ 2-668.11 
read_password_$swi tch 2-669 

pathname 

construct i ng 

pathname^ 2-642.16 
pathname_$component 2-643 
pathname_$component_check 

2-644 
di rectory 

get_pdir_ 2-369 
get_wdir_ 2-378 
expand_pathname_$add_suf f i x 
2-246 
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pathname (cont) 

expand_pathname $component 

2-247, 2-2^8 
mani pul at ion 

absolute_pathname__ 2-6 
absol ute_pathname_$add_s 

2-7 

expand__pathname_ 2-245 
get_shortest_path_ 2-373 
hcs_$chname_f i 1 e 2-397 
hcs_$chname__seg 2-399 
referencing 

h c s_$ f s_g e t_pa t h_n ame 
2-410 

pathname_ subroutine 2-642.16 

pathname_$component 2-643 

pathname_$component_check 
2-644 

pathname_$pathname_ 2-642.16 

phcs_$read_di sk__label 2-645 

physical volume 
ID 

f i nd_part i t ion_ 2-288 
i nformat ion 

mdc $pvname info 2-586 » 2 
reservi ng 

resource_control_$ reserve 
2-676 

resource_control_$cancel_id_s 
2-675 

resource_i nf o_ 2-682 
PL/I 

area assignment 

define_area_ 2-215 
data type conversion 

ass i gn__$computat i ona 1 

2-49 
error codes 

pi 1 io_$error_code 2-646 
I/O 

pi l_io__$get_iocb_ptr 
2-646 



PL/ 1 (cont) 

symbol information 
runtime symbol_i nf o_ 
2-699 

PL/I files 

extracting information 
pll_io_ 2-646 

pll_io_ subroutine 2-646 

pi l_io_$error_code 2-646 

pi l_io_$get_iocb_ptr 2-646 

poi nter 

bit offset 

add_bi t_of f set_ 2-9 
bit_offset_ 2-57 
set_bi t_offset_ 2-730 

cal 1 er 

cu_$cal 1 er_ptr 2-147 
cu_$generate_cal 1 2-151 

character offset 

add_char_of f set_ 2-10 
char_offset_ 2-84 
set_char_of f set_ 2-730 

entry value 

cu_$decode_entry_val ue 
2-149 

cu $make entry value 

2-155 
formatt i ng 

ioa_ 2-518 
runt ime_symbol_i nfo_$address 

2-700 
stack frame 

cu_$stack__f rame_ptr 2-160 

prepare_mc_restart_ subroutine 
2-647 

preparejnc restart_$repl ace 
2-648~ 

prepare_mc_restart_$retry 
2-648 

prepare_mc_restart_$tra 2-649 
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pr i ces 

system__i nf o__$abs_pr i ces 

2-841 ~ 
system_i nf o_$devi ce_pr i ces 

2-843 "~ 
system_i nf o_$ i o_pr i ces 

2-844 ~~ 
system_i nf o_$pr i ces 2-847 

pr i nt i ng 
of f 1 i ne 

iod_info_ 2-529 
system_i nfo_$ io_pr i ces 
2-844 
remote device 

remote_pr i nter_ 3" 138 
remote_telepr i nter_ 3~146 

pr i nt__cobol_error_ 2-650 

print_data_ subroutine 2-650 

pr i nt_data_$pr i nt_data_ 2-650 

process 

access pr i vi leges 

get_pr ivi leges_ 2-370 
AIM authorization 

get_process accessed ass_ 

2-371 " 
get_process_max_auth 
2-372 

blocked 

ipc_$biock 2-556 
cleanup handlers 

add_epi logue_handler_ 

execute_epi logue_ 2-245 
connect ion 

di al_manager_ 2-220 
CPU usage 

cpu_t i me_and_pag i ng_ 

dialjnanager $pr i vi 1 eged_att 

2-222~ 
disconnection handler 

sus_signal_handler_ 2-837 
hcs_$get_system_search_rules 
2-430 



process (cont) 
i nformation 

get_group_id_ 2-366 
get_group_id_$tag_star 
2-367 

get_process_id_ 2-372 
get_wdir_ 2-378 
hcs_$val idate_process id 

2-491 
i ni t i al i zat ion 
get_i ni t i al_r i ng_ 2-367 
hcs $get initial ring 

~ 2-4T9 
i nterrupt ion 

hphcs__$ ips_wakeup 2-507 
process directory 

get_pdir_ 2-369 
resource usage 

hcs_$get_process_usage 
2-424 
search rules 

hcs__$get_search_rules 
^2-429 

hcs_^ i n i t i a te__search_ru 1 es 
2-440 

process directory 
temporary segment 

get_temp_segments_ 2-377 
get_temp__segment_ 2-376 

process overseer 
sus_ condition 

sct__manager__$set 2-713 
sus_signal_handler__ 2-837 

prof i 1 e segment 
abbrev_ 2-3 

program 

variable information 
run t ime_symbol_i nf o_ 
2-699 

program tuning 

cost saving features 
cpu_t i me_and_pag i ng_ 
2-130 
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protection 

critical section of code 
hcs_$get_i ps_mask 2-1*19 
hcs_$reset__i ps_mask 2-1*58 
hcs_$set_i ps_mask 2-1*65 
set_iock_$lock 2-738 
set_lock_$unlock 2-71*0 

see access control 

see ring brackets 

protocol 

data transfer 

i bm_pc_ i o_ 3-5 1 
xmodem_io_ 3" 2 85 

punched cards 
of f 1 i ne output 
dprint_ 2-233 
iod_info_ 2-529 
system_i nf o_$ i o_pr i ces 
2-81*1+ 



Q 



qedx__ subroutine 2-650.3 

quer i es 

ask_ 2-37 
command query 2 — 3 1 
command__query_$yes_no 2-95 
dl_handler_ 2-231 
nd_handler_ 2-625 

question marks 

see star convention 

queue 
daemon 

dpr i nt_$queue_contents 
2-21*0 

quota 

accounting information 
hcs_$quota__move 2-1*51 

logical volume 
mdc_$set_volume_quota 
2-588 



quota (cont) 

master directories 

mdc_$set__mdi r_quota 2-588 

quoted strings 

requote__str i ng_ 2-675 



R 



random numbers 

random_$exponent i al 2-659 
random_$exponent i al_seq 
2-659 

random_$get_seed 2-660 
random_$normal 2-660 
r andom_$ norma l_ant 2-661 
random_$normal_ant_seq 
2-661 

random_$normal_seq 2-662 
random_$set_seed 2-663 
random_$uni f orm 2-663 
random_$uni f orm_ant 2-661* 
random_$uni f orm_ant_seq 
2-665 

random_$uni f orm_seq 2-665 
random_ subroutine 2-658 
random_$exponer.t i a 1 2-659 
random_$exponent i al__seq 2-659 
random_$get_seed 2-660 
random_$normal 2-660 
random_$normal_ant 2-661 
random__$normal_ant_seq 2-661 
random_$normal__seq 2-662 
random_$set_seed 2-663 
random_$uni f orm 2-663 
random $uni form__ant 2-661* 
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random_$uni f orm_ant_seq 2-665 

random_$uni f orm_seq 2-665 

rate structure 

system_i nf o_$max_rs_number 
2-845 

system_i nf o_$rs_name 2-848 
system_i nf o_$rs_number 
2-848 

rbf_ I/O module 3" 118 
rcp_ subroutine 2-668 
rcp_$attach 2-668.2 
rcp_$check_attach 2-668. 5 
rcp_$detach 2-668.6 
rcp_$get__status 2-668.7 

1 1 : - + i_cto Q 

I V- p V ■ I 9 I- I v^wwi v>wS <- UWU • G 

rdisk_ I/O module 3-122 

ready state 

cu_$get_ready_mode 2-152.2 
cu_$get__ready_procedure 
2-153 

cu_$ready_proc 2-155 
cu_$reset_ready_procedure 
2-157 

cu_$set_ready_mode 2-159 
cu_$set_ready procedure 
2-159 

read_al lowed_ function 
2-668.10 

read_password_ subroutine 
2-668. 11 

read_password_$swi ten 2-669 

read_wr i te_al lowed__ function 
2-670 



reconnect.ee 

sus_s ignal__handler_ 2-837 

record I/O 

record_stream_ 3" 132 
remote = i nput__ 3" 136 

record/stream conversion 
record_stream_ 3" 132 

record_stream_ I/O module 
3-132 

reference name 
creat i ng 

hcs_$ini tiate 2-437, A- 1 1 
hcs__$ini tiate_count 2-439 » 
A-13 
obtai ni ng 

hcs_$f s_get_ref_name 

" 2-411 " 
hcs_$f s_get_seg_ptr 2-411 
termi nat i ng 

hes $terminate file A- 16 
hcs_$ termi nate_name A- 17 
hcs_$ termi nate_noname 
A- 18 

hcs_$ termi nate_seg A- 19 
term_ 2-853 
term_$ref name 2-853 
term_$seg_ptr 2-854 
term_$s i ngl e_ref name 

2-854 
term_$unsnap 2-855 

rehash_ subroutine 2-671 

release_area_ subroutine 
2-671 

re 1 ease_temp_segments__ 
subroutine 2-673 

release_temp_segment_ 
subroutine 2-672 

remote batch facility 
gll5_ 3-34.1 
rbf_ 3-H8 
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remote batch facility (cont) 
remote_pr i nter_ 3" 138 
remote_punch_ 3" 144 
remote_teleprinter_ 3"146 

remote_i nput_ I/O module 
3-136 

remote_pr i nter_ I/O module 
3-138 

remote punch I/O module 
flkh 

remote_tel epr i nter_ I/O module 
3-U6 

renami ng 

hcs_$chname_f i 1 e 2-397 
hcs_$chname_seg 2-399 

request_id_ 2-674 

requote_str i ng_ subroutine 
2-675 

resource 
pr i ces 

system_i nf o_$resource_pr i ce 
2-847 

i ie ana 
" sa 9 c 

process 

hcs_$get_process_usage 
2-42J+ 

Resource Control Package (RCP) 
cv_rcp_attr i butes_ 2-176.1 
i nterpret_resource_desc_ 
2-514 

resource_control_ 2-675 
resource_i nf o_ 2-682 

resource_control__ subroutine 
2-675 

resource_control_$cancel_id_str 
2-675 



resource_control_$ reserve 
2-676 

resource__i nf o_ subroutine 
2-682 

resource_i nf o_$canon_name 
2-683 

resource_i nf o_$def aul ts 2-683 

resource_i nf o_$get_type 2-684 

resource_i nf o_$ 1 imi ts 2-685 

resource_i nf o_$ 1 ock_on_rel ease 
2-685 

resource_i nf o_$mates 2-686 
reversion_ procedure 2-686.1 

ring 0 

hardcore segments 
ringO_get_ 2-687 
r i ng_zero_peek_ 2-693 

HASP multiplexer 
hasp_host_ 3 _ 36 
hasp_workstat ion_ 3"44 

• ■ * 

master directory 
manipulation 
mdc_ 2-584 

ring brackets 
di rectory 

hcs_$get_d i rjr i ng_brackets 
2-417 " 

segment 

hcs_$get_r i ng_brackets 

" 2-427 
hcs $get_ring brackets seg 

~ 2-427 
hcs_$set_r i ng_brackets 
2-468 

ringO_get_ subroutine 2-687 
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r i ngO_get_$def S ni tion 2-687 

r i ngO_get_$def i n i t i on_g i ven__s 1 1 
2-688 

r i ngO_get_$name 2-689 

r i ngO_get_$ names 2-690 

r i ngO_get_$name_g i ven_s 1 1 
2-689 

r i ngO_get_$segptr 2-69 1 

r i ngO_get_$segptr_g i ven__s 1 1 
2-692 

r i ngs 

d i rectory 

hcs_$set_d i r_r i ng_brackets 
2-461 
I/O operations 
cross_r i ng_ 3~32 
cress r i n° i o fallow cross 
~2-136 

number 

get__ini tial_r ing_ 2-367 
get_ring_ 2-373 
val i dat ion 1 evel 

cu_$level_get 2-154 
cu_$level_set 2-154 

r i ng_zero_peek subroutine 

2-693 

r i ng_zero_peek_$by definition 
2-693 

r i ng_zero_peek_$by_name 2-694 

r i ng_zero_peek_$get_max_l ength 
2-695 

r i ng_zero_peek_$get_max_l_ptr 
~2-696 

root directory 

absol ute_pathname_ 2-6 



root directory (cont) 

absol ute_pathname_$add_suf f ix 
2-7 

expand_pathname_ 2-245 

expand_pathname_$add_suf f i x 
2-246 

get_shortest_path_ 2-373 

run units 

cleanup handlers 

add_ep i 1 ogue_hand 1 er_ 
2-11 

execute_epi logue_ 2-245 
debugg i ng 

run_$envi ronment_i nf o 
2-698 
i nvok i ng 

run_ 2-697 

runtime error 
COBOL 

pr i nt_cobol_error_ 2-650 
pr i nt_cobol_error_$swi tch 
2-650 

runt ime_symbol_i nf o_ 
subroutine 2-699 

runt ime_symbol_i nf o__$address 
2-700 

runt ime_symbol_i nfo_$array 
2-702 

runt ime_symbol info $array dims 
2-704 

runt ime_symbol_i nfo_$brother 
2-704 

runt ime_symbol_i nf o_$f ather 
2-705 

runt ime_symbol_i nfo_$f ather type 
2-705 

runt ime_symbol_i nf o_$ level 
2-705 
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runtime_symbol_J nfo__$name 
2-706 

runtime_symbol_i nfo_$next 
2-707 

runt ime_symbol_i nfo_$n_yar i ants 
2-706 

runt ime_symbol_i nfo_$son 
2-707 

runtime_symbol_i nf o_$successor 
2-708 

runtime_symbol_i nfo_$type 
2-708 

runt ime_symbol_i nf o_$var i ant 
2-710 

run_ subroutine 2-697 
run_$envi ronment_info_ 2-698 



safety switch 

hcs $get_safety sw 2-428 
hcs_$get_saf ety_sw_seg 

2-428.1 
hcs__$set_saf ety_sw 2-469 
hcs_$set_saf ety_sw_seg 

2-470 

SCT 

see system condition table 

sct_manager_ subroutine 2-712 

sct_manager_$cal l_handler 
2-712 ~~ 

sct_manager_$get 2-712 

sct__manager_$set 2-713 



search rules 
current 

hcs_$get_search_rul es 
2-429 

hcs_$get_system_search_rul es 

2-430 
i ni t i at i ng 

hcs_$ i n i t i ate_search_rul es 
2-440 

search_paths subroutine 
2-7U 

search_paths_$del ete_l ist 
2-720 

search_paths_$f i nd_al 1 2-715 

search_paths_$f i nd_di r 2-714 

search_paths_$get 2-716 

search_paths__$ i ni t_search__seg 
2-721 

search_paths_$ 1 i st 2-719 
search_paths__$set 2-718 
segment 

arrece COfl^ TO 1 

copy_acl_ 2-126 
hcs_$add_acl_entr i es 
2-384 

hcs_$add_i nacl_entr ies 
2-390 

hcs_$del ete_acl_entr i es 
2-403 

hcs__$del ete_i nac l_entr i es 

2-406 " 
hcs_$f s_get_mode 2-409 
hcs_$get_access_c 1 ass 

~ 2-414 
hcs_$get_access_c 1 ass_seg 

~ 2-415 
hcs_$l ist_acl 2-442 
hcs_$ 1 i st_i nacl 2-446 
hcs_$repl ace_acl 2-453 
hcs_$repl ace_i nacl 2-457 
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segment (cont) 
access modes 

cv_mode_ 2-172 
attr i butes 

hcs_$get_max_l ength 2-1*2 1 
hcs_$get_max_l ength_seg 
2-422 

hcs_$set_256K_swi tch 

~ 2-459 
hcs_$set_bc 2-1*60 
hcs_$set_bc_seg A- 14 
hcs_$set_max_l ength 2-466 
hcs_$set_max_l ength__seg 

~ 2-i+67 
author 

hcs_$get_author 2-1+16.4 
bit count author 

hcs_$get_bc_author 2-417 
count 

hcs__$h i gh_1 ow_seg_count 

2-436 
creat i ng 

create_data__segment_ 
2-131 

hcs_$append_branch 2-392 
hcs_$append_branchx 2-393 
hcs_$create__branch_ 2-400 
hcs_$make_seg 2-450 

del et i ng 

de1ete_ 2-218 
delete"$path 2-218 
delete_$ptr 2-220 
hcs__$del entry_f i le A-10 
hcs_$del entry_seg A- 11 

entry point bound 
hcs_$set_entry_bound 
2-463, 2-462.1 

hcs_$release segment_numbers 
2-452 " 

hcs_$reserve_segment_numbers 

2-458 
information 

1 ist_dir_info = 2-581 
i nspect i on 

dump_segment_ 2-240 
making addressable 

cv_ptr_ 2-174 

hcs_$ini tiate 2-437, A-ll 



segment (cont) 

making addressable 

hcs__$ i ni t i ate_count 2-439, 
A-13 

hcs_$make_entry 2-448 
hcs_$make_ptr 2-449 
hcs_$make_seg 2-450 
ini tiate_f i le_ 2-510 
making nonaddressabl e 
cv_ptr_$termi nate 2-174 
hcs_$termi nate_f i le A- 16 
hcs_$termi nate__name A- 17 
hcs_$termi nate_noname 
A- 18 

hcs_$termi nate_seg A- 19 
term_ 2-853 
term_$ref name 2-853 
term_$seg_ptr 2-854 
term_$s i ng 1 e_ref name 

2-854 
term_$unsnap 2-855 
manipulation 

hcs_$f s_move__f i le 2-412 

U»» (-To i~ em 0 — 1. II. 

1 1 <- O y l a mwvw_SSy Z. 

name manipulation 

hcs_$chname_f i le 2-397 

hcs_$chname_seg 2-399 
page faults 

mhcs_$get_seg_usage 2-604 

mhcs $get seg_usage__ptr 
"2-605 
pathname 

hcs_$ f s_ge t_pa th_name 
2-410 " 
reference name 

hcs $f s_get_ref_name 
~ 2-411 
ref erenci ng 

cv_entry_ 2-166 

hcs_$f s_get_seg_ptr 2-411 
r i ng 0 

ring0_get_ 2-687 

r i ng_zero_peek_ 2-693 
ring brackets 

hcs_$get_r i ng_brackets 
2-427 

hcs_$get_r i ng_brackets_seg 
2-427 " 
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segment (cont) 
ring brackets 

hcs_$set_r i ng_brackets 

~ 2-^68 
safety switch 

hcs_$get__saf ety_sw 2-1*28 
hcs_$get_saf ety_sw_seg 

2-^28.1 
hcs_$set_saf ety_sw 2-2*69 
h c s_$ s e t_s a f e t y _s w_s eg 
~ 2-470 
segment numbers 

hcs_$ini tiate_count 2-439, 
A-13 

hcs__$make_ptr 2-449 
status 

hcs_$status_ 2-480 
hcs_$status_long 2-484 
hcs_$status_mi nf 2-488 
hcs__$status_mi ns 2-489 
suf f i xes 

suf f i xed_name__ 2-834 
swi tches 
changing 

hcs_$set_dnzp_sw 2-462 
h c s__$ s e t_d nz p_sw_s eg 
2-462.1 

temporary 

get_temp_segments_ 2-377 
get_temp_segment_ 2-376 

release temp segments 
2-673 

rel ease_temp_segment_ 
2-672 
truncat i ng 

hcs_$truncate_f i le 2-490 

hcs_$truncate__seg A- 19 
unique identifier 

hcs_$get_uid_seg 2-432 

segment loading table (SLT) 
r i ngO_get_$def i ni t ion 2-688 
ringO get $name given sit 
2-689 

r i ngO_get_$segptr_g i ven_s 1 1 
2-692 

send_as_request_ subroutine 
2-721 



send_as_request_$block 2-721 

send_as__r eques t__$ no_b 1 ock 
2-722 

send_mai 1_ subroutine 2-722.1 

send_ma i l_$access_c 1 ass 2-723 

sendjnai l_$path 2-724 

sendjnai l_$path access class 
2-724 

send_message__ subroutine 
2-727 

send_message_$acknowl edge 
2-728 

send_message_$express 2-728 

send_message_$noti f y_mai 1 
2-729 

set_b i t__of f set__ function 
~ 2-730 

set_char_of f set_ function 
2-730 

set__external_var i abl e_$ locate 
- 2 _ 732 

set_ext_var i abl e_ subroutine 
~ 2-731 

set_ext_var i ab 1 e_$po i nter 
2-733 

set_ext_var i able_$star_heap 
2-734 

set_lock_ subroutine 2-737 
set_lock_$lock 2-738 
set_lock_$unlock 2-740 
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shared data bases 
see al so vf i 1 e_ 
set_lock_$lock 2-738 
set_lock_$unlock 2-740 

shcs_$set_f orce_wr i te_l imi t 
2-741 

shift information 

datebin_$shif t 2-208-6 
pr i ces 

system_i rtf o_$devi ce_pr i ces 
2-843 

system_i nf o_$next_sh i f t_change 
2-846 

system_i nf o_$sh i f t_tabl e 
2-849 

shutdown 

system_i nf o_$ 1 ast__shutdown 
2-844 

system__i nf o_$next_shutdown 
2-846 

s i gnal 

act i ve_f nc_err__$suppress_name 
2-9 

condition information 
f i nd_cond i t i on_i nf o_ 

2-285 
condition mechanism 

signal^ 2-741 
see condi t ions 
status conditions 
act i ve_f nc_err_ 2-7 
com_err_ 2-89 
com_err_$suppress_name 
~" 2-90 

signal_ subroutine 2-741 

signal_io_ I/O module 3" 147 

slave process 

d i al_manager_$pr i vi leged_att 
~ 2-222 

SLT 

see segment loading table 



sort i ng 

bit strings 

sort_i tems_$bit 2-742.1 
sort_i tems_i nd i rect_$bi t 

2-745 
character string 

sort_i tems_$vary ing__char 

2-742.5 
sort_i tems_i nd i rect__$char 

2-746 
data items 

sort_i tems__$general 
2-742.3 

numbers 

sor t_ i tems_$ f i xed_b i n 
2-742.2 

sort_i tems_i nd i rect_$adj_char 
2-744 

sor t_ i tems_ i nd i r ec t_$ f i xed_b 
2-747 

sor t_ i t ems_ i nd i r ec t_$ f 1 oa t_b 
2-747 

sort_i tems_ i nd i rect_$general 

*> _ "I I o 
I HO 

sort_i tems_i nd i rect_$vary i ng 
2-749 

sor t_i tems_ subroutine 2-742 

sort_i tems__$bi t 2-742.1 

sort_i tems_$char 2-742.2 

sort_i tems_$f ixed_bin 2-742.2 

sort__i tems__$f loat_bin 2-742.3 

sort_i tems_$general 2-742.3 

sort_i tems_$vary i ng_char 
2-742.5 

sort_i tems_i ndi rect_ 

subroutine 2-742.6 

sort items indirect_$adj_char 
~2-744~ 
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sort_i tems_i ndi rect_$bi t 
2-745 

sort__i tems_i ndi rect_$char 
2-746 

sort_i tems_indi rect_$f ixed_bin 
2-747 

sort i tems_i nd i rect_$f loat bin 
- 2-7^7 

sort_i tems_i ndi rect_$general 
2-748 

sort_i tems_indi rect_$var_char 
2-749 

sort_seg__ subroutine 2-750 

sort_seg_$seg 2-751 

sort__seg_$str i ng 2~757 

spg__r i ng_0_i nf o_ subroutine 
2-760 

spg_util_ subroutine 2-758 
spg_ut i l_$reset 2-759 
ssu__$abort_l i ne 2-760 
ssu_$abort_subsystem 2-762 
ssu_$add_i nf o_di r 2-763 
ssu_$add_request__tab1 e 2-764 
ssu_$appl y__request_ut i 1 2-765 
ssu_$arg_count 2-766 
ssu_$arg_l i st_ptr 2-767 
ssu_$arg_ptr 2-767 
ssu_$create_i nvocat ion 2-768 



ssu_$del ete_i nf o_di r 2-769 

ssu_$delete_request_tabl e 
2-770 ~ 

ssu_$destroy_i nvocat ion 2-771 

ssu_$eval uate_act i ve__str i ng 
2-771 

ssu_$execute__l i ne 2-773 

ssu_$execute_start_up 2-774 

ssu_$execute_str i ng 2-775 

ssu_$get_area 2-775 

ssu_$get_debug_mode 2-777 

ssu_$get_def aul t_procedure 
2-777 

ssu_$get_def aul t_rp_options 
2-778 

ssu_$get_ec_search__l i st 2-779 

ssu_$get_ec_subsystem_ptr 
2-779 

ssu_$get__ec_suf f i x 2-780 

ssu_$get_info_ptr 2-780 

ssu_$get_i nvocat i on_count 
2-781 

s s u_$ g e t 1 e v e 1 _n_s c i _p t r 
2-781 

ssu__$get_prev_sci_ptr 2-782 
ssu_$get_procedure 2-783 
ssu_$get_prompt 2-783 
ssu_$get_prompt_mode 2-784 
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ssu_$get_ready_mode 2-784 

ssu_$get_request_name 2-785 

ssu_$get_request_processor_opt 
2-786 

ssu_$get_subsystem_name 2-787 

ssu_$get__subsystem_vers i on 
2-788 

ssu $get_subsys_a__request_name 
2-787 

ssu_$get_temp_segment 2-788 

ssu_$ listen 2-792 

ssu_$l i st_i nfo__di rs 2-789 

ssu_$l i st_request_tables 
" 2-791 

ssu_$pr int_blast 2-793 

ssu_$pr i ntjnessage 2-794 

ssu_$record_usage 2-795 

ssu_$rel ease_area 2-796 

ssu_$rel ease_temp_segment 
2-796 

ssu__$reset_procedure 2-797 

ssu_$reset_request_processor_o 
2-798 

ssu_$return_arg 2-798 

ssu_$set_debug_mode 2-799 

ssu_$set_ec_search_J i st 2-800 

ssu_$set_ec_subsystem_ptr 
2-800 



ssu_$set_ec_suf f i x 2-801 

ssu_$set_i nf o__di rs 2-801 

ssu_$set_i nf o_ptr 2-802 

ssu_$set_procedure 2-803 

ssu_$set_prompt 2-804 

ssu_$set_prompt_mode 2-804 

ssu__$set_ready__mode 2-805 

ssu_$set_request_processor_opt 
2-806 

ssu_$set_request_tables 2-807 

ssu_$standalone_J nvocat ion 
2-808 

stack frame 

condition frame 

f i nd_cond i t i on_f rame_ 
2-284 

f i nd_condi t ion_i nfo_ 

2-285 
exami n i ng 

stu_$decode__runt ime_val ue 
2-809 

stu_$f i nd_runt ime_symbol 
2-814 

stu_$get_block 2-815 
stu_$get_map_i ndex 2-819 
stu_$get_runt ime_address 

~~ 2-820 
stu_$get_runt ime block 
2-821 

stu_$of f set_to_poi nter 
2-824 

stu_$poi nter_to_of f set 
2-825 

stu_$remote_f ormat 2-826 
extend i ng 

cu_$grow stack_frame 
2-153 
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stack frame (cont) 
history registers 

hcs_$h i story_regs_get 

~ 2-1*36.1 
hcs_$h i story_regs_set 

2-l»37 
on units 

conti nue__to_s i gnal_ 2-102 
poi nter 

cu_$stack__f rame_ptr 2-160 
reduci ng 

cu $shr i n'k_stack frame 
2-160 

s ize 

cu_$stack_f rame_s i ze 
2-160 

stu_$get_impl i c i t_qual i f i er 
2-815 

star convention 

check_star_name_ 2-87 
check_star_name_$check_st_n 
2-87 

check star_name_$entry 

2-88.3 
check__star__name_$path 

2-88. 4 
hcs_$star_ 2-1+71 
hcs__$star__di r_l i st__ 2-1*71* 
hcs_$star_l ist_ 2-1*79 
match star name 2-583 

statement map 

stu_$get_statement_map 
2-821* 

static handlers 

sct_manager_ 2-712 

sus__s i gna1_handl er_ 2-837 

static storage 
rei ni t ial izi ng 

term__$unsnap 2-855 
runtime information 

runtime symbol info 

2-699 
segments 

create_data_segment_ 
2-131 



status 

access control 

hcs_$status_mi ns 2-1*89 

di rectory 

hcs_$status_ 2-1*80 
hcs_$status_long 2-1*81* 
hcs_$status_mi nf 2-1*88 

1 i nk 

hcs_$status_ 2-1*80 
hcs_$status__long 2-1*81+ 
hcs_$statusjni nf 2-1*88 
segment 

create_data_segment_ 

2-131 " 
hcs_$status_ 2-1*80 
hcs_$status_long 2-1*81+ 
hcs_$status_mi nf 2-1*88 
hcs_$status_mi ns 2-1*89 

status code 

act i ve_f nc_err_$suppress_name 
2-9 
convers i on 

convert_status_code_ 
2-123 

cv_error_$name 2-168 
error messages 

act i ve__f nc__err_ 2-7 

com_err_ 2-89 

com_err_$suppress_name 
" 2-90 
PL/ I I/O 

pi l_i o_$error_code 2-61*6 

storage 

runtime information 
runt ime_symbol_i nfo_ 

2-699 
system free area 

g e t__s y s t em_f r ee__a r ea 
2-376 
temporary 

cu_$grow_stack_f rame 
2-153 

cu_$shr i nk_stack frame 
2-160 
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storage system 
file I/O 

vfile_ 3-219 
object 

access attributes 

hcs_$get_access_i nf o 
2-1*16 

hcs_$get_access_i nf o__seg 
2-1*16.2 

quota 

hcs_$quota_move 2-1*50.1 
hcs_$quota_read 2-1*51 

stream 1/0 
audit_ 3-23 
bisync_ 3"27 
gll5_ 3-3*1.1 
ibm2780_ 3"71* 
ibm3270_ 3"77 
ibm3780_ 3-86 
record_stream_ 3" 132 
remote_pr i nter_ 3" 138 
remote_punch_ 3-11*1* 
remote_tel epr i nter_ 3" 11*6 
tty_printer_ 3"217 

stream/record conversion 
record_stream__ 3 _ 1 32 

str i ng 

convers ion 

ar i thmet i c_to_asc i i_ 2-31 
char_to__numer i c_ 2-85 
cv_bin_ 2-161 
cv_dec_ 2-162 
cv__dec_check_ 2-163 
cv_f 1 oat_doub1 e_ 2-169 
cv_hex_ 2-171 
cv__hex_check_ 2-171 
cv_oct_ 2-173 
cv_oct_check_ 2-173 
ioa_ 2-5 18 

expansion 
abbrev_ 2-3 

quot i ng 

requote_str i ng_ 2-675 

search 

find_bit_ 2-271* 
find_char_ 2-276 



stu_ subroutine 2-809 

s tu_$decode_run t i me_va 1 ue 
2-809 

s tu_$decode_runt i me_va 1 ue_ext 
2-810 

stu_$f ind_block 2-812 

s tu_$f i nd_conta i n i ng_b 1 ock 
2-812 

stu_$f i ndjieader 2-813 

stu_$f i nd_runt ime_symbol 
2-811* 

stu_$get_block 2-815 

stu_$get_impl i c i t_qual i f i er 
2-815 

stu_$get_l ine 2-817 

stu_$get_l i ne_no 2-818 

stu_$get_locat ion 2-819 

stu__$get_map_J ndex 2-819 

stu_$get_runt ime address 
2-820 

stu_$get_runt ime__block 2-821 

stu_$get_runt ime_l ine_no 
2-822 

stu__$get_runt ime location 
2-823 

stu_$get_statement_map 2-821* 
stu_$of f set_to_poi nter 2-821* 
stu_$poi nter_to_of f set 2-825 
stu__$remote_f ormat 2-826 
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subsystem 

error messages 
sub_err_ 2-830 

subsystem utilities 

active string evaluation 
ssu_$return_arg 2-798 

area management 

ssu_$get_area 2-775 
ssu_$release_area 2-796 

argument processing 
ssu_$arg_count 2-766 
ssu_$return_arg 2-798 

debuggi ng 

ssu_$get_debug_mode 2-777 
ssu_$set_debug_mode 2-799 

error handl ing 

ssu_$abort_l i ne 2-760 
ssu_$abort__subsystem 
2-762 

ssu_$pr i nt_message 2-794 
exec_coms 

ssu_$execute__start up 
2-774 

ssu_$get_ec_search_l ist 

" 2-779 
ssu $get_ec_subsystem_ptr 

~ 2-779 
ssu_$get__ec_suf f ix 2-780 
ssu_$set_ec_search__l ist 
o-onn 

ssu_$set_ec_subsystem_ptr 

~ 2-800 "* 
ssu_$set_ec__suf f ix 2-801 
info directories 
ssu__$add_info__di r 2-763 
ssu_$delete__info_di r 

" 2-769 
ssu_$l ist_info_dirs 2-789 
ssu_$set__info_di rs 2-801 
i nformat ion 
ssu_$get_i nfo_ptr 2-780 
ssu_$get invocation count 
2-781 

ssu $get__ievel n sci ptr 

" 2-781 
ssu_$get_prev_sc i_ptr 
2-782 



subsystem utilities (cont) 
information 

ssu__$get_subsystem_name 

*" 2-787 
ssu_$get_subsystem_vers i on 

2-788 

ssu_$record_usage 2-795 
ssu_$set_i nf o_ptr 2-802 
i nvok i ng 
ssu $create_J nvocation 

~ 2-768 
ssu_$get_subsystem_name 

~ 2-787 
ssu_$standalone_i nvocation 

2-808 

1 i stener 

ssu_$ listen 2-792 

messages 

ssu__$pr i nt_bl ast 2-793 
ssu_$pr i nt_message 2-794 

poi nters 

ssu_$get_i nf o_ptr 2-780 
ssu_$get_l evel_n__sc i_ptr 
2-781 

ssu_$get_prev_sc i_ptr 
2-782 

ssu_$set_i nfo_ptr 2-802 
procedures 

ssu_$get_def au 1 t_procedure 
~\ 2-777 

ceil ^not nrftreHuro 0 — 1 Q1 
" " » ~ *-_r" ~ — — — • — — i \j ^ 

ssu_$reset_procedure 

~ 2-797 
ssu_$set__procedure 2-803 
prompts 

ssu_$get_prompt 2-783 
ssu_$get_prompt_mode 
2-784 

ssu_$set_prompt 2-801* 

ready processing 

ssu_$get_ready_mode 2-784 
ssu_$set_ready_mode 2-805 

request line execution 
ssu_$execute_l i ne 2-773 
ssu_$execute__str i ng 2-775 
ssu_$get_request_name 
2-785 



i-53 
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subsystem utilities (cont) 
request tables 

ssu_$add_request_tabl e 
2-761* 

ssu_$del ete_request_tabl e 

2-770 ~ 
ssu_$ 1 i st__request_tabl es 

2-791 

ssu_$set_request_tabl es 
2-807 

ssu_$eva1 uate_act i ve string 
2-771 

ssu_$get_def aul t_rp_options 
2-778 

ssu_$get_request_processor_o 
2-786 

ssu_$get_subsys_a_request_n 
2-787 

ssu_$reset_request_processor 
2-798 

ssu_$set_request_processor_o 

2-806 
start up 

ssu_$execute_s tar t_up 

2-774 
temporary segments 

ssu_$rel ease_temp_segment 

~ 2-796 
vers ion 

ssu_$get subsystem version 
2-788 

ssu_$pr i nt_blast 2-793 

subsystem ut I i t i es 
request tables 

ssu_$apply_request_ut i 1 
2-765 

sub_err__ subroutine 2-830 

suf f i xed_name_ subroutine 
2-834 

suff ixed_name_$f ind 2-834 

suf f i xed__name_$make 2-835 

suf f ixed__name_$new_suf f ix 
2-836 



suffixes 

expand_pathname_$add_suf f ix 
2-246 

expand_pathname__$component 
2-248 

suff ixed__name_$ find 2-834 
suf f i xed_name_$make 2-835 
suff i xed_name_$new__suf f i x 
2-836 

sus_signal_handler_ subroutine 
2-837 

sus_s i gnal_handler_$recon_ec_d 
2-838 

sus_si gnal_handler_$recon_ec_en 
2-837 

sweep_disk_ subroutine 2-838 
sweep_di sk_$di r_l i st 2-839 

_. _i : _ i. 1 1 ,j i.oi a 

swi tches 
chang i ng 

hcs__$set_dnzp_sw 2-462 
hcs_$set dnzp__sw_seg 
2-462.1 

don't null zero pages (dnzp) 
hcs_$set_dnzp__sw 2-462 
hcs_$set_dnzp_sw_seg 
2-462 . 1 
safety switch 

hcs_$get_safety_sw 2-428 
hcs_$get_saf ety_sw_seg 

2-428.1 
hcs_$set_saf ety_sw 2-469 
hcs_$set_saf ety_sw_seg 
2-470 

symbol table 
address 

stu_$get runtime address 
2-820 
conversion 

stu_$of f set_to_po i nter 
2-824 
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symbol table (cont) 
conversion 

stu_$poi nter_to_of f set__ 
2-825 
decodi ng 

s tu__$decode_runt i me_va 1 ue 

~ 2-809 ~ 
stu_$remote_format 2-826 
getting information 
runt ime__symbol_i nfo 

2-699 
i nformation 
stu_$get_l ine 2-817 
stu_$get_l i ne_no 2-818 
stu_$get_runt ime_l ine_no 

2-822 

stu_$get_statement_map 
2-824 
i nstruct ion 

stu_$get__locat ion 2-819 
object code 

s tu_$get_runt i me__l oca t i on 
2-823 
poi nters 

stu_$get_block 2-815 
stu_$get_runt ime_block 
2-821 
search i ng 

stu_$f ind_block 2-812 
stu_$f i nd_contai ni ng_block 
2-812 

stu_$f ind_header 2-813 
stu_$f i nd_runt ime_ symbol 

2-8U 
statement map 

stu_$get_map_i ndex 2-819 
stu_$get_impl ici t_qual if ier 
2-815 

synonym attachment 
syn_ 3-152 

syn_ I/O module 3-152 

system 

absentee information 
system_i nf o_$abs_chn 
2-841 



system (cont) 

access authorization 

get_systern_aim_attr ibutes_ 
2-374 

system__i nf o_$access_cei 1 ing 
2-842 

system_J nf o_$category_names 
2-842 

system_J nf o_$ 1 evel_names 

2-845 
clock reading 

clock_ 2-88.4 
compute__common_aim_cei 1 ing_ 

2-T00 

identifiers 

system_i nf o__$ i nstal lation_id 
2-844 

system_i nf o_$sys id 2-849 
system_J nf o_$t i ties 2-850 
1 oad 

system_i nf o__$users 2-851 
pr i ces 

system__i nf o_$abs_pr i ces 
2-841 

system_i nf o_$devi ce_pr i ces 
2-843 

system_i nf o_$ i o_pr i ces 
2-844 

system_i nf o_$pr i ces 2-847 
system_inf o__$resource_pr i ce 

rate structure 

system_i nf o_$max_rs_number 
2-845 

system_i nf o_$rs_name 
2-848 

system_i nf o_$rs_number 
2-848 
shift information 

datebin_$shif t 2-208.6 
system_i nf o_$shi f t_table 

2-849 
shutdown 

system_i nf o_$ 1 ast_shutdown 
2-844 

system_i nf o_$next_shutdown 
2-846 
startup time 

system_i nf o_$t imeup 2-850 
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system (cont) 

system_i nf o_$def aul t_abs_q 
2-842 

system i nf o_$next_sh i f t__c 
2-846 

system condition table (SCT) 
sct_manager_$cal l_handler 

~ 2-712 
sct_manager_$get 2-712 
sct_manager_$set 2-713 

system_info_ subroutine 2-840 

system_i nf o_$abs_chn 2-841 

system_i nf o_$abs_pr i ces 2-841 

system_i nf o_$access_cei 1 i ng 
2 r 842 

system__i nf o_$category_names 
2-842 

system_i nf o_$def aul t_abs_q 
2-842 

system_info $device prices 
2-843 

system info $instal lation_id 
2-844 ~ 

system_J nf o_$ i o_pr I ces 2-844 

system_i nf o_$ 1 ast_shutdown 
2-844 

system_i nf o_$ 1 evel names 
2-845 

system_i nf o_$max_rs_number 
2-845 

system__i nfo__$next_shi f t_change 
2-846 

system_i nf o_$next_shutdown 
2-846 



system_i nf o_$pr i ces 2-847 

system_i nf o_$resource_pr i ce 
2-847 

system_i nf o_$rs_name 2-848 

system_i nf o_$rs_number 2-848 

system__i nf o_$sh i f t_tabl e 
2-849 

system_i nf o_$sys i d 2-849 

system_i nf o_$t imeup 2-850 

system_i nf o_$t i t 1 es 2-850 

system_i nf o_$trusted_path 
2-851 

system_i nf o_$users 2-851 
system_info $version id 2-852 



T 



tape format 
ANSI 

tape_ansi_ 3-151 
ANSI standard 

ansi_tape_io_ 3*3 
IBM 

tape_ibm_ 3~161 
IBM standard 

ibm_tape_io_ 3 _ 55 
Multics standard 

tape_mult_ 3-176 
unstructured 

tape_nstd_ 3~ 180 

tape processing 
ibm_tape_io_ 3~55 
tape_ansi_ 3-151 
tape_ibm_ 3-161 

tape_ansi_ I/O module 3-151 
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tape_ibm_ I/O module 3-161 

tape_mult_ I/O module 3" 176 

tape_nstd_ I/O module 3-180 

tc_i o_ I/O modules 3- 185 

teco 
command 

see Multics Commands and 
Active Functions 
external macros 

teco_get_macro 2-852 

teco_get_macro_ subroutine 
2-852 

temporary segments 
creat i ng 

get_temp_segments_ 2-377 
get_temp_segment_ 2-376 
releasing 

release_area_ 2-671 
subsystem usage 

ssu_$release_temp_segment 
2-796 

termi nal 
I/O 

tty__ 3-187 
modes 

tty_ 3-187 
multiple terminals 

convert_di al_message_ 
2-120 

di al_manager_ 2-220 
dial__manager_$al low_dial s 
2-221 

remote 

ibm2780_ 3"74 
ibm3270^ 3-77 
ibm3780_ 3-86 
remote_i nput_ 3-136 
remote_tel epr 1 nter_ 3" 146 



termi nati ng 

dial connections 

dial_manager_$release_dial_id 
2-224 

dial_manager_$shutof f_dial s 
2-225 

dial _manager_$ term i na te_d_p 
2-226 "~ 

1 ink 

term_ 2-853 

term_$ref name 2-853 
reference name 

hcs_$ termi nate__name A- 17 

hcs_$termi nate_noname 
A-18 

term_ 2-853 

term__$ref name 2-853 

term_$seg_ptr 2-854 

term_$s i ngl e_ref name 
2-854 

term_$unsnap 2-855 
segment 

hcs_$ termi nate_f i le A- 16 

hcs__$ termi nate_seg A- 19 

term_ 2-853 

term_$ref name 2-853 

term_$seg__ptr 2-854 

termi nation 
process 
cleanup 

add_epi logue_handler_ 
" 2-11 

execute_epilogue_ 2-245 
run unit 
cleanup 

add_epi 1 oguejiandl er_ 
2-11 

execute_epi logue_ 2-245 
term__ subroutine 2-853 
term_$ref name 2-853 
term_$seg_ptr 2-854 
term_$s i ngl e_ref name 2-854 
term_$unsnap 2-855 
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text 

f ormatt i ng 

f ormat_document_ 2-290.1 
f ormat_document_$str i ng 

2-290.2 
f ormat_document_$swi ten 
2-290.3 

text editors 
qedx 

qedx_ 2-650.3 

text file 
Pascal 

pascal_ut i 1_ 2-642.13 

time 

convers i on 

encode_clock_value_ A~5 
see date and time 

time zones 
convers i on 

decode_c 1 ock_va 1 ue_$date_t 
A-3 

traci ng 

paging activity 

hcs_$get_page_trace 2-422 
runtime symbol table 

stu_ 2-809 
stack frame 

f i nd_cond i t i on_f r ame_ 

2-284 
f i nd_cond i t i on info 
2-285 

translation 

character 

asci i_to_ebcdic_ 2-32.1 
ebed i c_to_asc i i_ 2-243 

character strings 
mvt_ 2-624 

translators 
error messages 
1 ex_er ror_ 2-565 



translators (cont) 
i nclude file 

f ind_indude_f i le_ 2-287 
i nput 

lex_string_ 2-569 
i nstruction 

find_bit_ 2-274 

find_char_ 2-276 

truncat i ng 
segment 

hcs_$truncate_f i le 2-490 
hcs_$truncate_seg A- 19 

tty_ I/O module 3-187 

tty_printer_ I/O module 3-217 



U 



under f lows 

exponent control $fault un 
2-249 

exponent_control_$restar t un 
2-249 

unique identifier 
segment 

hcs_$get_uid_seg 2-432 

unl i nk i ng 

! nterprocedure reference 
term_ 2-853 
term $single_refname 

"2-854 
term__$unsnap 2-855 

usage data 

cpu_t ime_and_pagi ng_ 2-130 

useless output 
discard^ 3-33 

user 

access identifier 
get_group_id_ 2-366 
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user (cont) 

access identifier 

get_group_id_$tag_star 

2-367 
parameters 

get_pr i v i 1 eges_ 2-370 
User_id 

cv_userid_ 2-182 



V 



val idat ion 1 evel 
branch 

hcs_$get_user_ef fmode 

2-1*35 
di rectory 

hcs_$get_d i r_r i ng_brackets 
2-417 

hcs $set__d i r_r i ng_brackets 
2-^61 

segment 

hcs_$get_r i ng_brackets 
2-427 

hcs_$get_r i ng_brackets_seg 
2-427 

hcs_$set_r i ng_brackets 
2-468 

var iable 

runtime information 
runt ime_symbol_i nf o_ 
2-699 

set_ext_var i abl e_$star__heap 
2-734 

variable address 

runt ime_symbol_i nf o__$address 
2-700 

vf i 1 e_ 

control orders 3 - 233 
add_key 3"233 
delete_key 3-235 
error_status 3"237 
exclude 3-238 
file_status 3~244 
get_key 3~244 



vfile_ (cont) 
control orders 

max_rec_len 3~247 
mi n__block_size 3"248 
read_pos i t ion 3"250 
reassign_key 3"250 
record_status 3-252 
seek_head 3-258 
select 3-259 
set_f i lejock 3-260 
set_wai t_time 3-260 
truncate 3-261 

vfile__ I/O module 3-219 

virtual entries 
cv_entry_ 2-166 

virtual pointers 
cv_ptr_ 2-174 
cv_ptr_$termi nate 2-174 



W 



wakeup signal 

hcs_$wakeup 2-491 

window_io_ 1/0 module 3"263 

working directory 
change_wd i r_ 2-84 
def aul t 

change_def aul t_wdi r_ 2-83 
get_def aul t_wdi r_ 2-352 
get_wdir_ 2-378 



X 



xmodem_io_ 1/0 module 3-285 
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